Input: docs - split input docs into kernel- and user-facing
authorDmitry Torokhov <dmitry.torokhov@gmail.com>
Fri, 7 Apr 2017 01:08:42 +0000 (18:08 -0700)
committerDmitry Torokhov <dmitry.torokhov@gmail.com>
Tue, 18 Apr 2017 03:19:34 +0000 (20:19 -0700)
Split input documentation into several groups: kernel- and user-facing, and
notes about individual device drivers. Move device drivers docs into a
separate subdirectory.

Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
42 files changed:
Documentation/input/alps.rst [deleted file]
Documentation/input/amijoy.rst [deleted file]
Documentation/input/appletouch.rst [deleted file]
Documentation/input/atarikbd.rst [deleted file]
Documentation/input/bcm5974.rst [deleted file]
Documentation/input/cma3000_d0x.rst [deleted file]
Documentation/input/cs461x.rst [deleted file]
Documentation/input/devices/alps.rst [new file with mode: 0644]
Documentation/input/devices/amijoy.rst [new file with mode: 0644]
Documentation/input/devices/appletouch.rst [new file with mode: 0644]
Documentation/input/devices/atarikbd.rst [new file with mode: 0644]
Documentation/input/devices/bcm5974.rst [new file with mode: 0644]
Documentation/input/devices/cma3000_d0x.rst [new file with mode: 0644]
Documentation/input/devices/cs461x.rst [new file with mode: 0644]
Documentation/input/devices/edt-ft5x06.rst [new file with mode: 0644]
Documentation/input/devices/elantech.rst [new file with mode: 0644]
Documentation/input/devices/gpio-tilt.rst [new file with mode: 0644]
Documentation/input/devices/iforce-protocol.rst [new file with mode: 0644]
Documentation/input/devices/index.rst [new file with mode: 0644]
Documentation/input/devices/joystick-parport.rst [new file with mode: 0644]
Documentation/input/devices/ntrig.rst [new file with mode: 0644]
Documentation/input/devices/rotary-encoder.rst [new file with mode: 0644]
Documentation/input/devices/sentelic.rst [new file with mode: 0644]
Documentation/input/devices/walkera0701.rst [new file with mode: 0644]
Documentation/input/devices/xpad.rst [new file with mode: 0644]
Documentation/input/devices/yealink.rst [new file with mode: 0644]
Documentation/input/edt-ft5x06.rst [deleted file]
Documentation/input/elantech.rst [deleted file]
Documentation/input/gamepad.rst
Documentation/input/gpio-tilt.rst [deleted file]
Documentation/input/iforce-protocol.rst [deleted file]
Documentation/input/index.rst
Documentation/input/input-programming.rst
Documentation/input/input_kapi.rst [new file with mode: 0644]
Documentation/input/input_uapi.rst [new file with mode: 0644]
Documentation/input/joystick-parport.rst [deleted file]
Documentation/input/ntrig.rst [deleted file]
Documentation/input/rotary-encoder.rst [deleted file]
Documentation/input/sentelic.rst [deleted file]
Documentation/input/walkera0701.rst [deleted file]
Documentation/input/xpad.rst [deleted file]
Documentation/input/yealink.rst [deleted file]

diff --git a/Documentation/input/alps.rst b/Documentation/input/alps.rst
deleted file mode 100644 (file)
index 76a71a1..0000000
+++ /dev/null
@@ -1,387 +0,0 @@
-----------------------
-ALPS Touchpad Protocol
-----------------------
-
-Introduction
-------------
-Currently the ALPS touchpad driver supports seven protocol versions in use by
-ALPS touchpads, called versions 1, 2, 3, 4, 5, 6 and 7.
-
-Since roughly mid-2010 several new ALPS touchpads have been released and
-integrated into a variety of laptops and netbooks.  These new touchpads
-have enough behavior differences that the alps_model_data definition
-table, describing the properties of the different versions, is no longer
-adequate.  The design choices were to re-define the alps_model_data
-table, with the risk of regression testing existing devices, or isolate
-the new devices outside of the alps_model_data table.  The latter design
-choice was made.  The new touchpad signatures are named: "Rushmore",
-"Pinnacle", and "Dolphin", which you will see in the alps.c code.
-For the purposes of this document, this group of ALPS touchpads will
-generically be called "new ALPS touchpads".
-
-We experimented with probing the ACPI interface _HID (Hardware ID)/_CID
-(Compatibility ID) definition as a way to uniquely identify the
-different ALPS variants but there did not appear to be a 1:1 mapping.
-In fact, it appeared to be an m:n mapping between the _HID and actual
-hardware type.
-
-Detection
----------
-
-All ALPS touchpads should respond to the "E6 report" command sequence:
-E8-E6-E6-E6-E9. An ALPS touchpad should respond with either 00-00-0A or
-00-00-64 if no buttons are pressed. The bits 0-2 of the first byte will be 1s
-if some buttons are pressed.
-
-If the E6 report is successful, the touchpad model is identified using the "E7
-report" sequence: E8-E7-E7-E7-E9. The response is the model signature and is
-matched against known models in the alps_model_data_array.
-
-For older touchpads supporting protocol versions 3 and 4, the E7 report
-model signature is always 73-02-64. To differentiate between these
-versions, the response from the "Enter Command Mode" sequence must be
-inspected as described below.
-
-The new ALPS touchpads have an E7 signature of 73-03-50 or 73-03-0A but
-seem to be better differentiated by the EC Command Mode response.
-
-Command Mode
-------------
-
-Protocol versions 3 and 4 have a command mode that is used to read and write
-one-byte device registers in a 16-bit address space. The command sequence
-EC-EC-EC-E9 places the device in command mode, and the device will respond
-with 88-07 followed by a third byte. This third byte can be used to determine
-whether the devices uses the version 3 or 4 protocol.
-
-To exit command mode, PSMOUSE_CMD_SETSTREAM (EA) is sent to the touchpad.
-
-While in command mode, register addresses can be set by first sending a
-specific command, either EC for v3 devices or F5 for v4 devices. Then the
-address is sent one nibble at a time, where each nibble is encoded as a
-command with optional data. This encoding differs slightly between the v3 and
-v4 protocols.
-
-Once an address has been set, the addressed register can be read by sending
-PSMOUSE_CMD_GETINFO (E9). The first two bytes of the response contains the
-address of the register being read, and the third contains the value of the
-register. Registers are written by writing the value one nibble at a time
-using the same encoding used for addresses.
-
-For the new ALPS touchpads, the EC command is used to enter command
-mode. The response in the new ALPS touchpads is significantly different,
-and more important in determining the behavior.  This code has been
-separated from the original alps_model_data table and put in the
-alps_identify function.  For example, there seem to be two hardware init
-sequences for the "Dolphin" touchpads as determined by the second byte
-of the EC response.
-
-Packet Format
--------------
-
-In the following tables, the following notation is used::
-
- CAPITALS = stick, miniscules = touchpad
-
-?'s can have different meanings on different models, such as wheel rotation,
-extra buttons, stick buttons on a dualpoint, etc.
-
-PS/2 packet format
-------------------
-
-::
-
- byte 0:  0    0 YSGN XSGN    1    M    R    L
- byte 1: X7   X6   X5   X4   X3   X2   X1   X0
- byte 2: Y7   Y6   Y5   Y4   Y3   Y2   Y1   Y0
-
-Note that the device never signals overflow condition.
-
-For protocol version 2 devices when the trackpoint is used, and no fingers
-are on the touchpad, the M R L bits signal the combined status of both the
-pointingstick and touchpad buttons.
-
-ALPS Absolute Mode - Protocol Version 1
----------------------------------------
-
-::
-
- byte 0:  1    0    0    0    1   x9   x8   x7
- byte 1:  0   x6   x5   x4   x3   x2   x1   x0
- byte 2:  0    ?    ?    l    r    ?  fin  ges
- byte 3:  0    ?    ?    ?    ?   y9   y8   y7
- byte 4:  0   y6   y5   y4   y3   y2   y1   y0
- byte 5:  0   z6   z5   z4   z3   z2   z1   z0
-
-ALPS Absolute Mode - Protocol Version 2
----------------------------------------
-
-::
-
- byte 0:  1    ?    ?    ?    1  PSM  PSR  PSL
- byte 1:  0   x6   x5   x4   x3   x2   x1   x0
- byte 2:  0  x10   x9   x8   x7    ?  fin  ges
- byte 3:  0   y9   y8   y7    1    M    R    L
- byte 4:  0   y6   y5   y4   y3   y2   y1   y0
- byte 5:  0   z6   z5   z4   z3   z2   z1   z0
-
-Protocol Version 2 DualPoint devices send standard PS/2 mouse packets for
-the DualPoint Stick. The M, R and L bits signal the combined status of both
-the pointingstick and touchpad buttons, except for Dell dualpoint devices
-where the pointingstick buttons get reported separately in the PSM, PSR
-and PSL bits.
-
-Dualpoint device -- interleaved packet format
----------------------------------------------
-
-::
-
- byte 0:    1    1    0    0    1    1    1    1
- byte 1:    0   x6   x5   x4   x3   x2   x1   x0
- byte 2:    0  x10   x9   x8   x7    0  fin  ges
- byte 3:    0    0 YSGN XSGN    1    1    1    1
- byte 4:   X7   X6   X5   X4   X3   X2   X1   X0
- byte 5:   Y7   Y6   Y5   Y4   Y3   Y2   Y1   Y0
- byte 6:    0   y9   y8   y7    1    m    r    l
- byte 7:    0   y6   y5   y4   y3   y2   y1   y0
- byte 8:    0   z6   z5   z4   z3   z2   z1   z0
-
-Devices which use the interleaving format normally send standard PS/2 mouse
-packets for the DualPoint Stick + ALPS Absolute Mode packets for the
-touchpad, switching to the interleaved packet format when both the stick and
-the touchpad are used at the same time.
-
-ALPS Absolute Mode - Protocol Version 3
----------------------------------------
-
-ALPS protocol version 3 has three different packet formats. The first two are
-associated with touchpad events, and the third is associated with trackstick
-events.
-
-The first type is the touchpad position packet::
-
- byte 0:    1    ?   x1   x0    1    1    1    1
- byte 1:    0  x10   x9   x8   x7   x6   x5   x4
- byte 2:    0  y10   y9   y8   y7   y6   y5   y4
- byte 3:    0    M    R    L    1    m    r    l
- byte 4:    0   mt   x3   x2   y3   y2   y1   y0
- byte 5:    0   z6   z5   z4   z3   z2   z1   z0
-
-Note that for some devices the trackstick buttons are reported in this packet,
-and on others it is reported in the trackstick packets.
-
-The second packet type contains bitmaps representing the x and y axes. In the
-bitmaps a given bit is set if there is a finger covering that position on the
-given axis. Thus the bitmap packet can be used for low-resolution multi-touch
-data, although finger tracking is not possible.  This packet also encodes the
-number of contacts (f1 and f0 in the table below)::
-
- byte 0:    1    1   x1   x0    1    1    1    1
- byte 1:    0   x8   x7   x6   x5   x4   x3   x2
- byte 2:    0   y7   y6   y5   y4   y3   y2   y1
- byte 3:    0  y10   y9   y8    1    1    1    1
- byte 4:    0  x14  x13  x12  x11  x10   x9   y0
- byte 5:    0    1    ?    ?    ?    ?   f1   f0
-
-This packet only appears after a position packet with the mt bit set, and
-usually only appears when there are two or more contacts (although
-occasionally it's seen with only a single contact).
-
-The final v3 packet type is the trackstick packet::
-
- byte 0:    1    1   x7   y7    1    1    1    1
- byte 1:    0   x6   x5   x4   x3   x2   x1   x0
- byte 2:    0   y6   y5   y4   y3   y2   y1   y0
- byte 3:    0    1    0    0    1    0    0    0
- byte 4:    0   z4   z3   z2   z1   z0    ?    ?
- byte 5:    0    0    1    1    1    1    1    1
-
-ALPS Absolute Mode - Protocol Version 4
----------------------------------------
-
-Protocol version 4 has an 8-byte packet format::
-
- byte 0:    1    ?   x1   x0    1    1    1    1
- byte 1:    0  x10   x9   x8   x7   x6   x5   x4
- byte 2:    0  y10   y9   y8   y7   y6   y5   y4
- byte 3:    0    1   x3   x2   y3   y2   y1   y0
- byte 4:    0    ?    ?    ?    1    ?    r    l
- byte 5:    0   z6   z5   z4   z3   z2   z1   z0
- byte 6:    bitmap data (described below)
- byte 7:    bitmap data (described below)
-
-The last two bytes represent a partial bitmap packet, with 3 full packets
-required to construct a complete bitmap packet.  Once assembled, the 6-byte
-bitmap packet has the following format::
-
- byte 0:    0    1   x7   x6   x5   x4   x3   x2
- byte 1:    0   x1   x0   y4   y3   y2   y1   y0
- byte 2:    0    0    ?  x14  x13  x12  x11  x10
- byte 3:    0   x9   x8   y9   y8   y7   y6   y5
- byte 4:    0    0    0    0    0    0    0    0
- byte 5:    0    0    0    0    0    0    0  y10
-
-There are several things worth noting here.
-
- 1) In the bitmap data, bit 6 of byte 0 serves as a sync byte to
-    identify the first fragment of a bitmap packet.
-
- 2) The bitmaps represent the same data as in the v3 bitmap packets, although
-    the packet layout is different.
-
- 3) There doesn't seem to be a count of the contact points anywhere in the v4
-    protocol packets. Deriving a count of contact points must be done by
-    analyzing the bitmaps.
-
- 4) There is a 3 to 1 ratio of position packets to bitmap packets. Therefore
-    MT position can only be updated for every third ST position update, and
-    the count of contact points can only be updated every third packet as
-    well.
-
-So far no v4 devices with tracksticks have been encountered.
-
-ALPS Absolute Mode - Protocol Version 5
----------------------------------------
-This is basically Protocol Version 3 but with different logic for packet
-decode.  It uses the same alps_process_touchpad_packet_v3 call with a
-specialized decode_fields function pointer to correctly interpret the
-packets.  This appears to only be used by the Dolphin devices.
-
-For single-touch, the 6-byte packet format is::
-
- byte 0:    1    1    0    0    1    0    0    0
- byte 1:    0   x6   x5   x4   x3   x2   x1   x0
- byte 2:    0   y6   y5   y4   y3   y2   y1   y0
- byte 3:    0    M    R    L    1    m    r    l
- byte 4:   y10  y9   y8   y7  x10   x9   x8   x7
- byte 5:    0   z6   z5   z4   z3   z2   z1   z0
-
-For mt, the format is::
-
- byte 0:    1    1    1    n3   1   n2   n1   x24
- byte 1:    1   y7   y6    y5  y4   y3   y2    y1
- byte 2:    ?   x2   x1   y12 y11  y10   y9    y8
- byte 3:    0  x23  x22   x21 x20  x19  x18   x17
- byte 4:    0   x9   x8    x7  x6   x5   x4    x3
- byte 5:    0  x16  x15   x14 x13  x12  x11   x10
-
-ALPS Absolute Mode - Protocol Version 6
----------------------------------------
-
-For trackstick packet, the format is::
-
- byte 0:    1    1    1    1    1    1    1    1
- byte 1:    0   X6   X5   X4   X3   X2   X1   X0
- byte 2:    0   Y6   Y5   Y4   Y3   Y2   Y1   Y0
- byte 3:    ?   Y7   X7    ?    ?    M    R    L
- byte 4:   Z7   Z6   Z5   Z4   Z3   Z2   Z1   Z0
- byte 5:    0    1    1    1    1    1    1    1
-
-For touchpad packet, the format is::
-
- byte 0:    1    1    1    1    1    1    1    1
- byte 1:    0    0    0    0   x3   x2   x1   x0
- byte 2:    0    0    0    0   y3   y2   y1   y0
- byte 3:    ?   x7   x6   x5   x4    ?    r    l
- byte 4:    ?   y7   y6   y5   y4    ?    ?    ?
- byte 5:   z7   z6   z5   z4   z3   z2   z1   z0
-
-(v6 touchpad does not have middle button)
-
-ALPS Absolute Mode - Protocol Version 7
----------------------------------------
-
-For trackstick packet, the format is::
-
- byte 0:    0    1    0    0    1    0    0    0
- byte 1:    1    1    *    *    1    M    R    L
- byte 2:   X7    1   X5   X4   X3   X2   X1   X0
- byte 3:   Z6    1   Y6   X6    1   Y2   Y1   Y0
- byte 4:   Y7    0   Y5   Y4   Y3    1    1    0
- byte 5:  T&P    0   Z5   Z4   Z3   Z2   Z1   Z0
-
-For touchpad packet, the format is::
-
-         packet-fmt     b7     b6     b5     b4     b3     b2     b1     b0
- byte 0: TWO & MULTI     L      1      R      M      1   Y0-2   Y0-1   Y0-0
- byte 0: NEW             L      1   X1-5      1      1   Y0-2   Y0-1   Y0-0
- byte 1:             Y0-10   Y0-9   Y0-8   Y0-7   Y0-6   Y0-5   Y0-4   Y0-3
- byte 2:             X0-11      1  X0-10   X0-9   X0-8   X0-7   X0-6   X0-5
- byte 3:             X1-11      1   X0-4   X0-3      1   X0-2   X0-1   X0-0
- byte 4: TWO         X1-10    TWO   X1-9   X1-8   X1-7   X1-6   X1-5   X1-4
- byte 4: MULTI       X1-10    TWO   X1-9   X1-8   X1-7   X1-6   Y1-5      1
- byte 4: NEW         X1-10    TWO   X1-9   X1-8   X1-7   X1-6      0      0
- byte 5: TWO & NEW   Y1-10      0   Y1-9   Y1-8   Y1-7   Y1-6   Y1-5   Y1-4
- byte 5: MULTI       Y1-10      0   Y1-9   Y1-8   Y1-7   Y1-6    F-1    F-0
-
- L:         Left button
- R / M:     Non-clickpads: Right / Middle button
-            Clickpads: When > 2 fingers are down, and some fingers
-            are in the button area, then the 2 coordinates reported
-            are for fingers outside the button area and these report
-            extra fingers being present in the right / left button
-            area. Note these fingers are not added to the F field!
-            so if a TWO packet is received and R = 1 then there are
-            3 fingers down, etc.
- TWO:       1: Two touches present, byte 0/4/5 are in TWO fmt
-            0: If byte 4 bit 0 is 1, then byte 0/4/5 are in MULTI fmt
-               otherwise byte 0 bit 4 must be set and byte 0/4/5 are
-               in NEW fmt
- F:         Number of fingers - 3, 0 means 3 fingers, 1 means 4 ...
-
-
-ALPS Absolute Mode - Protocol Version 8
----------------------------------------
-
-Spoken by SS4 (73 03 14) and SS5 (73 03 28) hardware.
-
-The packet type is given by the APD field, bits 4-5 of byte 3.
-
-Touchpad packet (APD = 0x2)::
-
-           b7   b6   b5   b4   b3   b2   b1   b0
- byte 0:  SWM  SWR  SWL    1    1    0    0   X7
- byte 1:    0   X6   X5   X4   X3   X2   X1   X0
- byte 2:    0   Y6   Y5   Y4   Y3   Y2   Y1   Y0
- byte 3:    0  T&P    1    0    1    0    0   Y7
- byte 4:    0   Z6   Z5   Z4   Z3   Z2   Z1   Z0
- byte 5:    0    0    0    0    0    0    0    0
-
-SWM, SWR, SWL: Middle, Right, and Left button states
-
-Touchpad 1 Finger packet (APD = 0x0)::
-
-           b7   b6   b5   b4   b3   b2   b1   b0
- byte 0:  SWM  SWR  SWL    1    1   X2   X1   X0
- byte 1:   X9   X8   X7    1   X6   X5   X4   X3
- byte 2:    0  X11  X10  LFB   Y3   Y2   Y1   Y0
- byte 3:   Y5   Y4    0    0    1 TAPF2 TAPF1 TAPF0
- byte 4:  Zv7  Y11  Y10    1   Y9   Y8   Y7   Y6
- byte 5:  Zv6  Zv5  Zv4    0  Zv3  Zv2  Zv1  Zv0
-
-TAPF: ???
-LFB:  ???
-
-Touchpad 2 Finger packet (APD = 0x1)::
-
-           b7   b6   b5   b4   b3   b2   b1   b0
- byte 0:  SWM  SWR  SWL    1    1  AX6  AX5  AX4
- byte 1: AX11 AX10  AX9  AX8  AX7  AZ1  AY4  AZ0
- byte 2: AY11 AY10  AY9  CONT AY8  AY7  AY6  AY5
- byte 3:    0    0    0    1    1  BX6  BX5  BX4
- byte 4: BX11 BX10  BX9  BX8  BX7  BZ1  BY4  BZ0
- byte 5: BY11 BY10  BY9    0  BY8  BY7  BY5  BY5
-
-CONT: A 3-or-4 Finger packet is to follow
-
-Touchpad 3-or-4 Finger packet (APD = 0x3)::
-
-           b7   b6   b5   b4   b3   b2   b1   b0
- byte 0:  SWM  SWR  SWL    1    1  AX6  AX5  AX4
- byte 1: AX11 AX10  AX9  AX8  AX7  AZ1  AY4  AZ0
- byte 2: AY11 AY10  AY9  OVF  AY8  AY7  AY6  AY5
- byte 3:    0    0    1    1    1  BX6  BX5  BX4
- byte 4: BX11 BX10  BX9  BX8  BX7  BZ1  BY4  BZ0
- byte 5: BY11 BY10  BY9    0  BY8  BY7  BY5  BY5
-
-OVF: 5th finger detected
diff --git a/Documentation/input/amijoy.rst b/Documentation/input/amijoy.rst
deleted file mode 100644 (file)
index 8df7b11..0000000
+++ /dev/null
@@ -1,263 +0,0 @@
-~~~~~~~~~~~~~~~~~~~~~~~~~
-Amiga joystick extensions
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-
-Amiga 4-joystick parport extension
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Parallel port pins:
-
-
-=====  ======== ====   ==========
-Pin    Meaning  Pin    Meaning
-=====  ======== ====   ==========
- 2     Up1      6     Up2
- 3     Down1    7     Down2
- 4     Left1    8     Left2
- 5     Right1   9     Right2
-13     Fire1   11     Fire2
-18     Gnd1    18     Gnd2
-=====  ======== ====   ==========
-
-Amiga digital joystick pinout
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-=== ============
-Pin Meaning
-=== ============
-1   Up
-2   Down
-3   Left
-4   Right
-5   n/c
-6   Fire button
-7   +5V (50mA)
-8   Gnd
-9   Thumb button
-=== ============
-
-Amiga mouse pinout
-~~~~~~~~~~~~~~~~~~
-
-=== ============
-Pin Meaning
-=== ============
-1   V-pulse
-2   H-pulse
-3   VQ-pulse
-4   HQ-pulse
-5   Middle button
-6   Left button
-7   +5V (50mA)
-8   Gnd
-9   Right button
-=== ============
-
-Amiga analog joystick pinout
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-=== ==============
-Pin Meaning
-=== ==============
-1   Top button
-2   Top2 button
-3   Trigger button
-4   Thumb button
-5   Analog X
-6   n/c
-7   +5V (50mA)
-8   Gnd
-9   Analog Y
-=== ==============
-
-Amiga lightpen pinout
-~~~~~~~~~~~~~~~~~~~~~
-
-=== =============
-Pin Meaning
-=== =============
-1   n/c
-2   n/c
-3   n/c
-4   n/c
-5   Touch button
-6   /Beamtrigger
-7   +5V (50mA)
-8   Gnd
-9   Stylus button
-=== =============
-
--------------------------------------------------------------------------------
-
-======== === ==== ==== ====== ========================================
-NAME     rev ADDR type chip   Description
-======== === ==== ==== ====== ========================================
-JOY0DAT      00A   R   Denise Joystick-mouse 0 data (left vert, horiz)
-JOY1DAT      00C   R   Denise Joystick-mouse 1 data (right vert,horiz)
-======== === ==== ==== ====== ========================================
-
-        These addresses each read a 16 bit register. These in turn
-        are loaded from the MDAT serial stream and are clocked in on
-        the rising edge of SCLK. MLD output is used to parallel load
-        the external parallel-to-serial converter.This in turn is
-        loaded with the 4 quadrature inputs from each of two game
-        controller ports (8 total) plus 8 miscellaneous control bits
-        which are new for LISA and can be read in upper 8 bits of
-        LISAID.
-
-        Register bits are as follows:
-
-        - Mouse counter usage (pins  1,3 =Yclock, pins 2,4 =Xclock)
-
-======== === === === === === === === === ====== === === === === === === ===
-    BIT#  15  14  13  12  11  10  09  08     07  06  05  04  03  02  01  00
-======== === === === === === === === === ====== === === === === === === ===
-JOY0DAT   Y7  Y6  Y5  Y4  Y3  Y2  Y1  Y0     X7  X6  X5  X4  X3  X2  X1  X0
-JOY1DAT   Y7  Y6  Y5  Y4  Y3  Y2  Y1  Y0     X7  X6  X5  X4  X3  X2  X1  X0
-======== === === === === === === === === ====== === === === === === === ===
-
-        0=LEFT CONTROLLER PAIR, 1=RIGHT CONTROLLER PAIR.
-        (4 counters total). The bit usage for both left and right
-        addresses is shown below. Each 6 bit counter (Y7-Y2,X7-X2) is
-        clocked by 2 of the signals input from the mouse serial
-        stream. Starting with first bit received:
-
-         +-------------------+-----------------------------------------+
-         | Serial | Bit Name | Description                             |
-         +========+==========+=========================================+
-         |   0    | M0H      | JOY0DAT Horizontal Clock                |
-         +--------+----------+-----------------------------------------+
-         |   1    | M0HQ     | JOY0DAT Horizontal Clock (quadrature)   |
-         +--------+----------+-----------------------------------------+
-         |   2    | M0V      | JOY0DAT Vertical Clock                  |
-         +--------+----------+-----------------------------------------+
-         |   3    | M0VQ     | JOY0DAT Vertical Clock  (quadrature)    |
-         +--------+----------+-----------------------------------------+
-         |   4    | M1V      | JOY1DAT Horizontal Clock                |
-         +--------+----------+-----------------------------------------+
-         |   5    | M1VQ     | JOY1DAT Horizontal Clock (quadrature)   |
-         +--------+----------+-----------------------------------------+
-         |   6    | M1V      | JOY1DAT Vertical Clock                  |
-         +--------+----------+-----------------------------------------+
-         |   7    | M1VQ     | JOY1DAT Vertical Clock (quadrature)     |
-         +--------+----------+-----------------------------------------+
-
-         Bits 1 and 0 of each counter (Y1-Y0,X1-X0) may be
-         read to determine the state of the related input signal pair.
-         This allows these pins to double as joystick switch inputs.
-         Joystick switch closures can be deciphered as follows:
-
-         +------------+------+---------------------------------+
-         | Directions | Pin# | Counter bits                    |
-         +============+======+=================================+
-         | Forward    |  1   | Y1 xor Y0 (BIT#09 xor BIT#08)   |
-         +------------+------+---------------------------------+
-         | Left       |  3   | Y1                              |
-         +------------+------+---------------------------------+
-         | Back       |  2   | X1 xor X0 (BIT#01 xor BIT#00)   |
-         +------------+------+---------------------------------+
-         | Right      |  4   | X1                              |
-         +------------+------+---------------------------------+
-
--------------------------------------------------------------------------------
-
-========  === ==== ==== ====== =================================================
-NAME      rev ADDR type chip    Description
-========  === ==== ==== ====== =================================================
-JOYTEST       036   W   Denise  Write to all 4  joystick-mouse counters at once.
-========  === ==== ==== ====== =================================================
-
-                  Mouse counter write test data:
-
-========= === === === === === === === === ====== === === === === === === ===
-     BIT#  15  14  13  12  11  10  09  08     07  06  05  04  03  02  01  00
-========= === === === === === === === === ====== === === === === === === ===
-  JOYxDAT  Y7  Y6  Y5  Y4  Y3  Y2  xx  xx     X7  X6  X5  X4  X3  X2  xx  xx
-  JOYxDAT  Y7  Y6  Y5  Y4  Y3  Y2  xx  xx     X7  X6  X5  X4  X3  X2  xx  xx
-========= === === === === === === === === ====== === === === === === === ===
-
--------------------------------------------------------------------------------
-
-======= === ==== ==== ====== ========================================
-NAME    rev ADDR type chip   Description
-======= === ==== ==== ====== ========================================
-POT0DAT  h  012   R   Paula  Pot counter data left pair (vert, horiz)
-POT1DAT  h  014   R   Paula  Pot counter data right pair (vert,horiz)
-======= === ==== ==== ====== ========================================
-
-        These addresses each read a pair of 8 bit pot counters.
-        (4 counters total). The bit assignment for both
-        addresses is shown below. The counters are stopped by signals
-        from 2 controller connectors (left-right) with 2 pins each.
-
-====== === === === === === === === === ====== === === === === === === ===
-  BIT#  15  14  13  12  11  10  09  08     07  06  05  04  03  02  01  00
-====== === === === === === === === === ====== === === === === === === ===
- RIGHT  Y7  Y6  Y5  Y4  Y3  Y2  Y1  Y0     X7  X6  X5  X4  X3  X2  X1  X0
-  LEFT  Y7  Y6  Y5  Y4  Y3  Y2  Y1  Y0     X7  X6  X5  X4  X3  X2  X1  X0
-====== === === === === === === === === ====== === === === === === === ===
-
-         +--------------------------+-------+
-         | CONNECTORS               | PAULA |
-         +-------+------+-----+-----+-------+
-         | Loc.  | Dir. | Sym | pin | pin   |
-         +=======+======+=====+=====+=======+
-         | RIGHT | Y    | RX  | 9   | 33    |
-         +-------+------+-----+-----+-------+
-         | RIGHT | X    | RX  | 5   | 32    |
-         +-------+------+-----+-----+-------+
-         | LEFT  | Y    | LY  | 9   | 36    |
-         +-------+------+-----+-----+-------+
-         | LEFT  | X    | LX  | 5   | 35    |
-         +-------+------+-----+-----+-------+
-
-         With normal (NTSC or PAL) horiz. line rate, the pots will
-         give a full scale (FF) reading with about 500kohms in one
-         frame time. With proportionally faster horiz line times,
-         the counters will count proportionally faster.
-         This should be noted when doing variable beam displays.
-
--------------------------------------------------------------------------------
-
-====== === ==== ==== ====== ================================================
-NAME   rev ADDR type chip   Description
-====== === ==== ==== ====== ================================================
-POTGO      034   W   Paula  Pot port (4 bit) bi-direction and data, and pot
-                           counter start.
-====== === ==== ==== ====== ================================================
-
--------------------------------------------------------------------------------
-
-====== === ==== ==== ====== ================================================
-NAME   rev ADDR type chip   Description
-====== === ==== ==== ====== ================================================
-POTINP     016   R   Paula  Pot pin data read
-====== === ==== ==== ====== ================================================
-
-        This register controls a 4 bit bi-direction I/O port
-        that shares the same 4 pins as the 4 pot counters above.
-
-         +-------+----------+---------------------------------------------+
-         | BIT#  | FUNCTION | DESCRIPTION                                 |
-         +=======+==========+=============================================+
-         | 15    | OUTRY    | Output enable for Paula pin 33              |
-         +-------+----------+---------------------------------------------+
-         | 14    | DATRY    | I/O data Paula pin 33                       |
-         +-------+----------+---------------------------------------------+
-         | 13    | OUTRX    | Output enable for Paula pin 32              |
-         +-------+----------+---------------------------------------------+
-         | 12    | DATRX    | I/O data Paula pin 32                       |
-         +-------+----------+---------------------------------------------+
-         | 11    | OUTLY    | Out put enable for Paula pin 36             |
-         +-------+----------+---------------------------------------------+
-         | 10    | DATLY    | I/O data Paula pin 36                       |
-         +-------+----------+---------------------------------------------+
-         | 09    | OUTLX    | Output enable for Paula pin 35              |
-         +-------+----------+---------------------------------------------+
-         | 08    | DATLX    | I/O data  Paula pin 35                      |
-         +-------+----------+---------------------------------------------+
-         | 07-01 |   X      | Not used                                    |
-         +-------+----------+---------------------------------------------+
-         | 00    | START    | Start pots (dump capacitors,start counters) |
-         +-------+----------+---------------------------------------------+
diff --git a/Documentation/input/appletouch.rst b/Documentation/input/appletouch.rst
deleted file mode 100644 (file)
index c94470e..0000000
+++ /dev/null
@@ -1,94 +0,0 @@
-.. include:: <isonum.txt>
-
-----------------------------------
-Apple Touchpad Driver (appletouch)
-----------------------------------
-
-:Copyright: |copy| 2005 Stelian Pop <stelian@popies.net>
-
-appletouch is a Linux kernel driver for the USB touchpad found on post
-February 2005 and October 2005 Apple Aluminium Powerbooks.
-
-This driver is derived from Johannes Berg's appletrackpad driver [#f1]_,
-but it has been improved in some areas:
-
-       * appletouch is a full kernel driver, no userspace program is necessary
-       * appletouch can be interfaced with the synaptics X11 driver, in order
-         to have touchpad acceleration, scrolling, etc.
-
-Credits go to Johannes Berg for reverse-engineering the touchpad protocol,
-Frank Arnold for further improvements, and Alex Harper for some additional
-information about the inner workings of the touchpad sensors. Michael
-Hanselmann added support for the October 2005 models.
-
-Usage
------
-
-In order to use the touchpad in the basic mode, compile the driver and load
-the module. A new input device will be detected and you will be able to read
-the mouse data from /dev/input/mice (using gpm, or X11).
-
-In X11, you can configure the touchpad to use the synaptics X11 driver, which
-will give additional functionalities, like acceleration, scrolling, 2 finger
-tap for middle button mouse emulation, 3 finger tap for right button mouse
-emulation, etc. In order to do this, make sure you're using a recent version of
-the synaptics driver (tested with 0.14.2, available from [#f2]_), and configure
-a new input device in your X11 configuration file (take a look below for an
-example). For additional configuration, see the synaptics driver documentation::
-
-       Section "InputDevice"
-               Identifier      "Synaptics Touchpad"
-               Driver          "synaptics"
-               Option          "SendCoreEvents"        "true"
-               Option          "Device"                "/dev/input/mice"
-               Option          "Protocol"              "auto-dev"
-               Option          "LeftEdge"              "0"
-               Option          "RightEdge"             "850"
-               Option          "TopEdge"               "0"
-               Option          "BottomEdge"            "645"
-               Option          "MinSpeed"              "0.4"
-               Option          "MaxSpeed"              "1"
-               Option          "AccelFactor"           "0.02"
-               Option          "FingerLow"             "0"
-               Option          "FingerHigh"            "30"
-               Option          "MaxTapMove"            "20"
-               Option          "MaxTapTime"            "100"
-               Option          "HorizScrollDelta"      "0"
-               Option          "VertScrollDelta"       "30"
-               Option          "SHMConfig"             "on"
-       EndSection
-
-       Section "ServerLayout"
-               ...
-               InputDevice     "Mouse"
-               InputDevice     "Synaptics Touchpad"
-       ...
-       EndSection
-
-Fuzz problems
--------------
-
-The touchpad sensors are very sensitive to heat, and will generate a lot of
-noise when the temperature changes. This is especially true when you power-on
-the laptop for the first time.
-
-The appletouch driver tries to handle this noise and auto adapt itself, but it
-is not perfect. If finger movements are not recognized anymore, try reloading
-the driver.
-
-You can activate debugging using the 'debug' module parameter. A value of 0
-deactivates any debugging, 1 activates tracing of invalid samples, 2 activates
-full tracing (each sample is being traced)::
-
-       modprobe appletouch debug=1
-
-or::
-
-       echo "1" > /sys/module/appletouch/parameters/debug
-
-
-.. Links:
-
-.. [#f1] http://johannes.sipsolutions.net/PowerBook/touchpad/
-
-.. [#f2] `<http://web.archive.org/web/*/http://web.telia.com/~u89404340/touchpad/index.html>`_
diff --git a/Documentation/input/atarikbd.rst b/Documentation/input/atarikbd.rst
deleted file mode 100644 (file)
index 745e7a1..0000000
+++ /dev/null
@@ -1,820 +0,0 @@
-====================================
-Intelligent Keyboard (ikbd) Protocol
-====================================
-
-
-Introduction
-============
-
-The Atari Corp. Intelligent Keyboard (ikbd) is a general purpose keyboard
-controller that is flexible enough that it can be used in a variety of
-products without modification. The keyboard, with its microcontroller,
-provides a convenient connection point for a mouse and switch-type joysticks.
-The ikbd processor also maintains a time-of-day clock with one second
-resolution.
-The ikbd has been designed to be general enough that it can be used with a
-variety of new computer products. Product variations in a number of
-keyswitches, mouse resolution, etc. can be accommodated.
-The ikbd communicates with the main processor over a high speed bi-directional
-serial interface. It can function in a variety of modes to facilitate
-different applications of the keyboard,  joysticks, or mouse. Limited use of
-the controller is possible in applications in which only a unidirectional
-communications medium is available by carefully designing the default modes.
-
-Keyboard
-========
-
-The keyboard always returns key make/break scan codes. The ikbd generates
-keyboard scan codes for each key press and release. The key scan make (key
-closure) codes start at 1, and are defined in Appendix A. For example, the
-ISO key position in the scan code table should exist even if no keyswitch
-exists in that position on a particular keyboard. The break code for each key
-is obtained by ORing 0x80 with the make code.
-
-The special codes 0xF6 through 0xFF are reserved for use as follows:
-
-=================== ====================================================
-    Code            Command
-=================== ====================================================
-    0xF6            status report
-    0xF7            absolute mouse position record
-    0xF8-0xFB       relative mouse position records (lsbs determined by
-                    mouse button states)
-    0xFC            time-of-day
-    0xFD            joystick report (both sticks)
-    0xFE            joystick 0 event
-    0xFF            joystick 1 event
-=================== ====================================================
-
-The two shift keys return different scan codes in this mode. The ENTER key
-and the RETurn key are also distinct.
-
-Mouse
-=====
-
-The mouse port should be capable of supporting a mouse with resolution of
-approximately 200 counts (phase changes or 'clicks') per inch of travel. The
-mouse should be scanned at a rate that will permit accurate tracking at
-velocities up to 10 inches per second.
-The ikbd can report mouse motion in three distinctly different ways. It can
-report relative motion, absolute motion in a coordinate system maintained
-within the ikbd, or by converting mouse motion into keyboard cursor control
-key equivalents.
-The mouse buttons can be treated as part of the mouse or as additional
-keyboard keys.
-
-Relative Position Reporting
----------------------------
-
-In relative position mode, the ikbd will return relative mouse position
-records whenever a mouse event occurs. A mouse event consists of a mouse
-button being pressed or released, or motion in either axis exceeding a
-settable threshold of motion. Regardless of the threshold, all bits of
-resolution are returned to the host computer.
-Note that the ikbd may return mouse relative position reports with
-significantly more than the threshold delta x or y. This may happen since no
-relative mouse motion events will be generated: (a) while the keyboard has
-been 'paused' ( the event will be stored until keyboard communications is
-resumed) (b) while any event is being transmitted.
-
-The relative mouse position record is a three byte record of the form
-(regardless of keyboard mode)::
-
-    %111110xy           ; mouse position record flag
-                        ; where y is the right button state
-                        ; and x is the left button state
-    X                   ; delta x as twos complement integer
-    Y                   ; delta y as twos complement integer
-
-Note that the value of the button state bits should be valid even if the
-MOUSE BUTTON ACTION has set the buttons to act like part of the keyboard.
-If the accumulated motion before the report packet is generated exceeds the
-+127...-128 range, the motion is broken into multiple packets.
-Note that the sign of the delta y reported is a function of the Y origin
-selected.
-
-Absolute Position reporting
----------------------------
-
-The ikbd can also maintain absolute mouse position. Commands exist for
-resetting the mouse position, setting X/Y scaling, and interrogating the
-current mouse position.
-
-Mouse Cursor Key Mode
----------------------
-
-The ikbd can translate mouse motion into the equivalent cursor keystrokes.
-The number of mouse clicks per keystroke is independently programmable in
-each axis. The ikbd internally maintains mouse motion information to the
-highest resolution available, and merely generates a pair of cursor key events
-for each multiple of the scale factor.
-Mouse motion produces the cursor key make code immediately followed by the
-break code for the appropriate cursor key. The mouse buttons produce scan
-codes above those normally assigned for the largest envisioned keyboard (i.e.
-LEFT=0x74 & RIGHT=0x75).
-
-Joystick
-========
-
-Joystick Event Reporting
-------------------------
-
-In this mode, the ikbd generates a record whenever the joystick position is
-changed (i.e. for each opening or closing of a joystick switch or trigger).
-
-The joystick event record is two bytes of the form::
-
-    %1111111x           ; Joystick event marker
-                        ; where x is Joystick 0 or 1
-    %x000yyyy           ; where yyyy is the stick position
-                        ; and x is the trigger
-
-Joystick Interrogation
-----------------------
-
-The current state of the joystick ports may be interrogated at any time in
-this mode by sending an 'Interrogate Joystick' command to the ikbd.
-
-The ikbd response to joystick interrogation is a three byte report of the form::
-
-    0xFD                ; joystick report header
-    %x000yyyy           ; Joystick 0
-    %x000yyyy           ; Joystick 1
-                        ; where x is the trigger
-                        ; and yyy is the stick position
-
-Joystick Monitoring
--------------------
-
-A mode is available that devotes nearly all of the keyboard communications
-time to reporting the state of the joystick ports at a user specifiable rate.
-It remains in this mode until reset or commanded into another mode. The PAUSE
-command in this mode not only stop the output but also temporarily stops
-scanning the joysticks (samples are not queued).
-
-Fire Button Monitoring
-----------------------
-
-A mode is provided to permit monitoring a single input bit at a high rate. In
-this mode the ikbd monitors the state of the Joystick 1 fire button at the
-maximum rate permitted by the serial communication channel. The data is packed
-8 bits per byte for transmission to the host. The ikbd remains in this mode
-until reset or commanded into another mode. The PAUSE command in this mode not
-only stops the output but also temporarily stops scanning the button (samples
-are not queued).
-
-Joystick Key Code Mode
-----------------------
-
-The ikbd may be commanded to translate the use of either joystick into the
-equivalent cursor control keystroke(s). The ikbd provides a single breakpoint
-velocity joystick cursor.
-Joystick events produce the make code, immediately followed by the break code
-for the appropriate cursor motion keys. The trigger or fire buttons of the
-joysticks produce pseudo key scan codes above those used by the largest key
-matrix envisioned (i.e. JOYSTICK0=0x74, JOYSTICK1=0x75).
-
-Time-of-Day Clock
-=================
-
-The ikbd also maintains a time-of-day clock for the system. Commands are
-available to set and interrogate the timer-of-day clock. Time-keeping is
-maintained down to a resolution of one second.
-
-Status Inquiries
-================
-
-The current state of ikbd modes and parameters may be found by sending status
-inquiry commands that correspond to the ikbd set commands.
-
-Power-Up Mode
-=============
-
-The keyboard controller will perform a simple self-test on power-up to detect
-major controller faults (ROM checksum and RAM test) and such things as stuck
-keys. Any keys down at power-up are presumed to be stuck, and their BREAK
-(sic) code is returned (which without the preceding MAKE code is a flag for a
-keyboard error). If the controller self-test completes without error, the code
-0xF0 is returned. (This code will be used to indicate the version/release of
-the ikbd controller. The first release of the ikbd is version 0xF0, should
-there be a second release it will be 0xF1, and so on.)
-The ikbd defaults to a mouse position reporting with threshold of 1 unit in
-either axis and the Y=0 origin at the top of the screen, and joystick event
-reporting mode for joystick 1, with both buttons being logically assigned to
-the mouse. After any joystick command, the ikbd assumes that joysticks are
-connected to both Joystick0 and Joystick1. Any mouse command (except MOUSE
-DISABLE) then causes port 0 to again be scanned as if it were a mouse, and
-both buttons are logically connected to it. If a mouse disable command is
-received while port 0 is presumed to be a mouse, the button is logically
-assigned to Joystick1 (until the mouse is reenabled by another mouse command).
-
-ikbd Command Set
-================
-
-This section contains a list of commands that can be sent to the ikbd. Command
-codes (such as 0x00) which are not specified should perform no operation
-(NOPs).
-
-RESET
------
-
-::
-
-    0x80
-    0x01
-
-N.B. The RESET command is the only two byte command understood by the ikbd.
-Any byte following an 0x80 command byte other than 0x01 is ignored (and causes
-the 0x80 to be ignored).
-A reset may also be caused by sending a break lasting at least 200mS to the
-ikbd.
-Executing the RESET command returns the keyboard to its default (power-up)
-mode and parameter settings. It does not affect the time-of-day clock.
-The RESET command or function causes the ikbd to perform a simple self-test.
-If the test is successful, the ikbd will send the code of 0xF0 within 300mS
-of receipt of the RESET command (or the end of the break, or power-up). The
-ikbd will then scan the key matrix for any stuck (closed) keys. Any keys found
-closed will cause the break scan code to be generated (the break code arriving
-without being preceded by the make code is a flag for a key matrix error).
-
-SET MOUSE BUTTON ACTION
------------------------
-
-::
-
-    0x07
-    %00000mss           ; mouse button action
-                        ;       (m is presumed = 1 when in MOUSE KEYCODE mode)
-                        ; mss=0xy, mouse button press or release causes mouse
-                        ;  position report
-                        ;  where y=1, mouse key press causes absolute report
-                        ;  and x=1, mouse key release causes absolute report
-                        ; mss=100, mouse buttons act like keys
-
-This command sets how the ikbd should treat the buttons on the mouse. The
-default mouse button action mode is %00000000, the buttons are treated as part
-of the mouse logically.
-When buttons act like keys, LEFT=0x74 & RIGHT=0x75.
-
-SET RELATIVE MOUSE POSITION REPORTING
--------------------------------------
-
-::
-
-    0x08
-
-Set relative mouse position reporting. (DEFAULT) Mouse position packets are
-generated asynchronously by the ikbd whenever motion exceeds the setable
-threshold in either axis (see SET MOUSE THRESHOLD). Depending upon the mouse
-key mode, mouse position reports may also be generated when either mouse
-button is pressed or released. Otherwise the mouse buttons behave as if they
-were keyboard keys.
-
-SET ABSOLUTE MOUSE POSITIONING
-------------------------------
-
-::
-
-    0x09
-    XMSB                ; X maximum (in scaled mouse clicks)
-    XLSB
-    YMSB                ; Y maximum (in scaled mouse clicks)
-    YLSB
-
-Set absolute mouse position maintenance. Resets the ikbd maintained X and Y
-coordinates.
-In this mode, the value of the internally maintained coordinates does NOT wrap
-between 0 and large positive numbers. Excess motion below 0 is ignored. The
-command sets the maximum positive value that can be attained in the scaled
-coordinate system. Motion beyond that value is also ignored.
-
-SET MOUSE KEYCODE MOSE
-----------------------
-
-::
-
-    0x0A
-    deltax              ; distance in X clicks to return (LEFT) or (RIGHT)
-    deltay              ; distance in Y clicks to return (UP) or (DOWN)
-
-Set mouse monitoring routines to return cursor motion keycodes instead of
-either RELATIVE or ABSOLUTE motion records. The ikbd returns the appropriate
-cursor keycode after mouse travel exceeding the user specified deltas in
-either axis. When the keyboard is in key scan code mode, mouse motion will
-cause the make code immediately followed by the break code. Note that this
-command is not affected by the mouse motion origin.
-
-SET MOUSE THRESHOLD
--------------------
-
-::
-
-    0x0B
-    X                   ; x threshold in mouse ticks (positive integers)
-    Y                   ; y threshold in mouse ticks (positive integers)
-
-This command sets the threshold before a mouse event is generated. Note that
-it does NOT affect the resolution of the data returned to the host. This
-command is valid only in RELATIVE MOUSE POSITIONING mode. The thresholds
-default to 1 at RESET (or power-up).
-
-SET MOUSE SCALE
----------------
-
-::
-
-    0x0C
-    X                   ; horizontal mouse ticks per internal X
-    Y                   ; vertical mouse ticks per internal Y
-
-This command sets the scale factor for the ABSOLUTE MOUSE POSITIONING mode.
-In this mode, the specified number of mouse phase changes ('clicks') must
-occur before the internally maintained coordinate is changed by one
-(independently scaled for each axis). Remember that the mouse position
-information is available only by interrogating the ikbd in the ABSOLUTE MOUSE
-POSITIONING mode unless the ikbd has been commanded to report on button press
-or release (see SET MOSE BUTTON ACTION).
-
-INTERROGATE MOUSE POSITION
---------------------------
-
-::
-
-    0x0D
-    Returns:
-            0xF7       ; absolute mouse position header
-    BUTTONS
-            0000dcba   ; where a is right button down since last interrogation
-                       ; b is right button up since last
-                       ; c is left button down since last
-                       ; d is left button up since last
-            XMSB       ; X coordinate
-            XLSB
-            YMSB       ; Y coordinate
-            YLSB
-
-The INTERROGATE MOUSE POSITION command is valid when in the ABSOLUTE MOUSE
-POSITIONING mode, regardless of the setting of the MOUSE BUTTON ACTION.
-
-LOAD MOUSE POSITION
--------------------
-
-::
-
-    0x0E
-    0x00                ; filler
-    XMSB                ; X coordinate
-    XLSB                ; (in scaled coordinate system)
-    YMSB                ; Y coordinate
-    YLSB
-
-This command allows the user to preset the internally maintained absolute
-mouse position.
-
-SET Y=0 AT BOTTOM
------------------
-
-::
-
-    0x0F
-
-This command makes the origin of the Y axis to be at the bottom of the
-logical coordinate system internal to the ikbd for all relative or absolute
-mouse motion. This causes mouse motion toward the user to be negative in sign
-and away from the user to be positive.
-
-SET Y=0 AT TOP
---------------
-
-::
-
-    0x10
-
-Makes the origin of the Y axis to be at the top of the logical coordinate
-system within the ikbd for all relative or absolute mouse motion. (DEFAULT)
-This causes mouse motion toward the user to be positive in sign and away from
-the user to be negative.
-
-RESUME
-------
-
-::
-
-    0x11
-
-Resume sending data to the host. Since any command received by the ikbd after
-its output has been paused also causes an implicit RESUME this command can be
-thought of as a NO OPERATION command. If this command is received by the ikbd
-and it is not PAUSED, it is simply ignored.
-
-DISABLE MOUSE
--------------
-
-::
-
-    0x12
-
-All mouse event reporting is disabled (and scanning may be internally
-disabled). Any valid mouse mode command resumes mouse motion monitoring. (The
-valid mouse mode commands are SET RELATIVE MOUSE POSITION REPORTING, SET
-ABSOLUTE MOUSE POSITIONING, and SET MOUSE KEYCODE MODE. )
-N.B. If the mouse buttons have been commanded to act like keyboard keys, this
-command DOES affect their actions.
-
-PAUSE OUTPUT
-------------
-
-::
-
-    0x13
-
-Stop sending data to the host until another valid command is received. Key
-matrix activity is still monitored and scan codes or ASCII characters enqueued
-(up to the maximum supported by the microcontroller) to be sent when the host
-allows the output to be resumed. If in the JOYSTICK EVENT REPORTING mode,
-joystick events are also queued.
-Mouse motion should be accumulated while the output is paused. If the ikbd is
-in RELATIVE MOUSE POSITIONING REPORTING mode, motion is accumulated beyond the
-normal threshold limits to produce the minimum number of packets necessary for
-transmission when output is resumed. Pressing or releasing either mouse button
-causes any accumulated motion to be immediately queued as packets, if the
-mouse is in RELATIVE MOUSE POSITION REPORTING mode.
-Because of the limitations of the microcontroller memory this command should
-be used sparingly, and the output should not be shut of for more than <tbd>
-milliseconds at a time.
-The output is stopped only at the end of the current 'even'. If the PAUSE
-OUTPUT command is received in the middle of a multiple byte report, the packet
-will still be transmitted to conclusion and then the PAUSE will take effect.
-When the ikbd is in either the JOYSTICK MONITORING mode or the FIRE BUTTON
-MONITORING mode, the PAUSE OUTPUT command also temporarily stops the
-monitoring process (i.e. the samples are not enqueued for transmission).
-
-SET JOYSTICK EVENT REPORTING
-----------------------------
-
-::
-
-    0x14
-
-Enter JOYSTICK EVENT REPORTING mode (DEFAULT). Each opening or closure of a
-joystick switch or trigger causes a joystick event record to be generated.
-
-SET JOYSTICK INTERROGATION MODE
--------------------------------
-
-::
-
-    0x15
-
-Disables JOYSTICK EVENT REPORTING. Host must send individual JOYSTICK
-INTERROGATE commands to sense joystick state.
-
-JOYSTICK INTERROGATE
---------------------
-
-::
-
-    0x16
-
-Return a record indicating the current state of the joysticks. This command
-is valid in either the JOYSTICK EVENT REPORTING mode or the JOYSTICK
-INTERROGATION MODE.
-
-SET JOYSTICK MONITORING
------------------------
-
-::
-
-    0x17
-    rate                ; time between samples in hundredths of a second
-    Returns: (in packets of two as long as in mode)
-            %000000xy   ; where y is JOYSTICK1 Fire button
-                        ; and x is JOYSTICK0 Fire button
-            %nnnnmmmm   ; where m is JOYSTICK1 state
-                        ; and n is JOYSTICK0 state
-
-Sets the ikbd to do nothing but monitor the serial command line, maintain the
-time-of-day clock, and monitor the joystick. The rate sets the interval
-between joystick samples.
-N.B. The user should not set the rate higher than the serial communications
-channel will allow the 2 bytes packets to be transmitted.
-
-SET FIRE BUTTON MONITORING
---------------------------
-
-::
-
-    0x18
-    Returns: (as long as in mode)
-            %bbbbbbbb   ; state of the JOYSTICK1 fire button packed
-                        ; 8 bits per byte, the first sample if the MSB
-
-Set the ikbd to do nothing but monitor the serial command line, maintain the
-time-of-day clock, and monitor the fire button on Joystick 1. The fire button
-is scanned at a rate that causes 8 samples to be made in the time it takes for
-the previous byte to be sent to the host (i.e. scan rate = 8/10 * baud rate).
-The sample interval should be as constant as possible.
-
-SET JOYSTICK KEYCODE MODE
--------------------------
-
-::
-
-    0x19
-    RX                  ; length of time (in tenths of seconds) until
-                        ; horizontal velocity breakpoint is reached
-    RY                  ; length of time (in tenths of seconds) until
-                        ; vertical velocity breakpoint is reached
-    TX                  ; length (in tenths of seconds) of joystick closure
-                        ; until horizontal cursor key is generated before RX
-                        ; has elapsed
-    TY                  ; length (in tenths of seconds) of joystick closure
-                        ; until vertical cursor key is generated before RY
-                        ; has elapsed
-    VX                  ; length (in tenths of seconds) of joystick closure
-                        ; until horizontal cursor keystrokes are generated
-                        ; after RX has elapsed
-    VY                  ; length (in tenths of seconds) of joystick closure
-                        ; until vertical cursor keystrokes are generated
-                        ; after RY has elapsed
-
-In this mode, joystick 0 is scanned in a way that simulates cursor keystrokes.
-On initial closure, a keystroke pair (make/break) is generated. Then up to Rn
-tenths of seconds later, keystroke pairs are generated every Tn tenths of
-seconds. After the Rn breakpoint is reached, keystroke pairs are generated
-every Vn tenths of seconds. This provides a velocity (auto-repeat) breakpoint
-feature.
-Note that by setting RX and/or Ry to zero, the velocity feature can be
-disabled. The values of TX and TY then become meaningless, and the generation
-of cursor 'keystrokes' is set by VX and VY.
-
-DISABLE JOYSTICKS
------------------
-
-::
-
-    0x1A
-
-Disable the generation of any joystick events (and scanning may be internally
-disabled). Any valid joystick mode command resumes joystick monitoring. (The
-joystick mode commands are SET JOYSTICK EVENT REPORTING, SET JOYSTICK
-INTERROGATION MODE, SET JOYSTICK MONITORING, SET FIRE BUTTON MONITORING, and
-SET JOYSTICK KEYCODE MODE.)
-
-TIME-OF-DAY CLOCK SET
----------------------
-
-::
-
-    0x1B
-    YY                  ; year (2 least significant digits)
-    MM                  ; month
-    DD                  ; day
-    hh                  ; hour
-    mm                  ; minute
-    ss                  ; second
-
-All time-of-day data should be sent to the ikbd in packed BCD format.
-Any digit that is not a valid BCD digit should be treated as a 'don't care'
-and not alter that particular field of the date or time. This permits setting
-only some subfields of the time-of-day clock.
-
-INTERROGATE TIME-OF-DAT CLOCK
------------------------------
-
-::
-
-    0x1C
-    Returns:
-            0xFC        ; time-of-day event header
-            YY          ; year (2 least significant digits)
-            MM          ; month
-            DD          ; day
-            hh          ; hour
-            mm          ; minute
-            ss          ; second
-
-    All time-of-day is sent in packed BCD format.
-
-MEMORY LOAD
------------
-
-::
-
-    0x20
-    ADRMSB              ; address in controller
-    ADRLSB              ; memory to be loaded
-    NUM                 ; number of bytes (0-128)
-    { data }
-
-This command permits the host to load arbitrary values into the ikbd
-controller memory. The time between data bytes must be less than 20ms.
-
-MEMORY READ
------------
-
-::
-
-    0x21
-    ADRMSB              ; address in controller
-    ADRLSB              ; memory to be read
-    Returns:
-            0xF6        ; status header
-            0x20        ; memory access
-            { data }    ; 6 data bytes starting at ADR
-
-This command permits the host to read from the ikbd controller memory.
-
-CONTROLLER EXECUTE
-------------------
-
-::
-
-    0x22
-    ADRMSB              ; address of subroutine in
-    ADRLSB              ; controller memory to be called
-
-This command allows the host to command the execution of a subroutine in the
-ikbd controller memory.
-
-STATUS INQUIRIES
-----------------
-
-::
-
-    Status commands are formed by inclusively ORing 0x80 with the
-    relevant SET command.
-
-    Example:
-    0x88 (or 0x89 or 0x8A)  ; request mouse mode
-    Returns:
-            0xF6        ; status response header
-            mode        ; 0x08 is RELATIVE
-                        ; 0x09 is ABSOLUTE
-                        ; 0x0A is KEYCODE
-            param1      ; 0 is RELATIVE
-                        ; XMSB maximum if ABSOLUTE
-                        ; DELTA X is KEYCODE
-            param2      ; 0 is RELATIVE
-                        ; YMSB maximum if ABSOLUTE
-                        ; DELTA Y is KEYCODE
-            param3      ; 0 if RELATIVE
-                        ; or KEYCODE
-                        ; YMSB is ABSOLUTE
-            param4      ; 0 if RELATIVE
-                        ; or KEYCODE
-                        ; YLSB is ABSOLUTE
-            0           ; pad
-            0
-
-The STATUS INQUIRY commands request the ikbd to return either the current mode
-or the parameters associated with a given command. All status reports are
-padded to form 8 byte long return packets. The responses to the status
-requests are designed so that the host may store them away (after stripping
-off the status report header byte) and later send them back as commands to
-ikbd to restore its state. The 0 pad bytes will be treated as NOPs by the
-ikbd.
-
-    Valid STATUS INQUIRY commands are::
-
-            0x87    mouse button action
-            0x88    mouse mode
-            0x89
-            0x8A
-            0x8B    mnouse threshold
-            0x8C    mouse scale
-            0x8F    mouse vertical coordinates
-            0x90    ( returns       0x0F Y=0 at bottom
-                            0x10 Y=0 at top )
-            0x92    mouse enable/disable
-                    ( returns       0x00 enabled)
-                            0x12 disabled )
-            0x94    joystick mode
-            0x95
-            0x96
-            0x9A    joystick enable/disable
-                    ( returns       0x00 enabled
-                            0x1A disabled )
-
-It is the (host) programmer's responsibility to have only one unanswered
-inquiry in process at a time.
-STATUS INQUIRY commands are not valid if the ikbd is in JOYSTICK MONITORING
-mode or FIRE BUTTON MONITORING mode.
-
-
-SCAN CODES
-==========
-
-The key scan codes returned by the ikbd are chosen to simplify the
-implementation of GSX.
-
-GSX Standard Keyboard Mapping
-
-======= ============
-Hex    Keytop
-======= ============
-01     Esc
-02     1
-03     2
-04     3
-05     4
-06     5
-07     6
-08     7
-09     8
-0A     9
-0B     0
-0C     \-
-0D     \=
-0E     BS
-0F     TAB
-10     Q
-11     W
-12     E
-13     R
-14     T
-15     Y
-16     U
-17     I
-18     O
-19     P
-1A     [
-1B     ]
-1C     RET
-1D     CTRL
-1E     A
-1F     S
-20     D
-21     F
-22     G
-23     H
-24     J
-25     K
-26     L
-27     ;
-28     '
-29     \`
-2A     (LEFT) SHIFT
-2B     \\
-2C     Z
-2D     X
-2E     C
-2F     V
-30     B
-31     N
-32     M
-33     ,
-34     .
-35     /
-36     (RIGHT) SHIFT
-37     { NOT USED }
-38     ALT
-39     SPACE BAR
-3A     CAPS LOCK
-3B     F1
-3C     F2
-3D     F3
-3E     F4
-3F     F5
-40     F6
-41     F7
-42     F8
-43     F9
-44     F10
-45     { NOT USED }
-46     { NOT USED }
-47     HOME
-48     UP ARROW
-49     { NOT USED }
-4A     KEYPAD -
-4B     LEFT ARROW
-4C     { NOT USED }
-4D     RIGHT ARROW
-4E     KEYPAD +
-4F     { NOT USED }
-50     DOWN ARROW
-51     { NOT USED }
-52     INSERT
-53     DEL
-54     { NOT USED }
-5F     { NOT USED }
-60     ISO KEY
-61     UNDO
-62     HELP
-63     KEYPAD (
-64     KEYPAD /
-65     KEYPAD *
-66     KEYPAD *
-67     KEYPAD 7
-68     KEYPAD 8
-69     KEYPAD 9
-6A     KEYPAD 4
-6B     KEYPAD 5
-6C     KEYPAD 6
-6D     KEYPAD 1
-6E     KEYPAD 2
-6F     KEYPAD 3
-70     KEYPAD 0
-71     KEYPAD .
-72     KEYPAD ENTER
-======= ============
diff --git a/Documentation/input/bcm5974.rst b/Documentation/input/bcm5974.rst
deleted file mode 100644 (file)
index 4aca199..0000000
+++ /dev/null
@@ -1,70 +0,0 @@
-.. include:: <isonum.txt>
-
-------------------------
-BCM5974 Driver (bcm5974)
-------------------------
-
-:Copyright: |copy| 2008-2009   Henrik Rydberg <rydberg@euromail.se>
-
-The USB initialization and package decoding was made by Scott Shawcroft as
-part of the touchd user-space driver project:
-
-:Copyright: |copy| 2008        Scott Shawcroft (scott.shawcroft@gmail.com)
-
-The BCM5974 driver is based on the appletouch driver:
-
-:Copyright: |copy| 2001-2004   Greg Kroah-Hartman (greg@kroah.com)
-:Copyright: |copy| 2005                Johannes Berg (johannes@sipsolutions.net)
-:Copyright: |copy| 2005                Stelian Pop (stelian@popies.net)
-:Copyright: |copy| 2005                Frank Arnold (frank@scirocco-5v-turbo.de)
-:Copyright: |copy| 2005                Peter Osterlund (petero2@telia.com)
-:Copyright: |copy| 2005                Michael Hanselmann (linux-kernel@hansmi.ch)
-:Copyright: |copy| 2006                Nicolas Boichat (nicolas@boichat.ch)
-
-This driver adds support for the multi-touch trackpad on the new Apple
-Macbook Air and Macbook Pro laptops. It replaces the appletouch driver on
-those computers, and integrates well with the synaptics driver of the Xorg
-system.
-
-Known to work on Macbook Air, Macbook Pro Penryn and the new unibody
-Macbook 5 and Macbook Pro 5.
-
-Usage
------
-
-The driver loads automatically for the supported usb device ids, and
-becomes available both as an event device (/dev/input/event*) and as a
-mouse via the mousedev driver (/dev/input/mice).
-
-USB Race
---------
-
-The Apple multi-touch trackpads report both mouse and keyboard events via
-different interfaces of the same usb device. This creates a race condition
-with the HID driver, which, if not told otherwise, will find the standard
-HID mouse and keyboard, and claim the whole device. To remedy, the usb
-product id must be listed in the mouse_ignore list of the hid driver.
-
-Debug output
-------------
-
-To ease the development for new hardware version, verbose packet output can
-be switched on with the debug kernel module parameter. The range [1-9]
-yields different levels of verbosity. Example (as root)::
-
-    echo -n 9 > /sys/module/bcm5974/parameters/debug
-
-    tail -f /var/log/debug
-
-    echo -n 0 > /sys/module/bcm5974/parameters/debug
-
-Trivia
-------
-
-The driver was developed at the ubuntu forums in June 2008 [#f1]_, and now has
-a more permanent home at bitmath.org [#f2]_.
-
-.. Links
-
-.. [#f1] http://ubuntuforums.org/showthread.php?t=840040
-.. [#f2] http://bitmath.org/code/
diff --git a/Documentation/input/cma3000_d0x.rst b/Documentation/input/cma3000_d0x.rst
deleted file mode 100644 (file)
index 6f40c17..0000000
+++ /dev/null
@@ -1,139 +0,0 @@
-Kernel driver for CMA3000-D0x
-=============================
-
-Supported chips:
-* VTI CMA3000-D0x
-
-Datasheet:
-  CMA3000-D0X Product Family Specification 8281000A.02.pdf
-  <http://www.vti.fi/en/>
-
-:Author: Hemanth V <hemanthv@ti.com>
-
-
-Description
------------
-
-CMA3000 Tri-axis accelerometer supports Motion detect, Measurement and
-Free fall modes.
-
-Motion Detect Mode:
-    Its the low power mode where interrupts are generated only
-    when motion exceeds the defined thresholds.
-
-Measurement Mode:
-    This mode is used to read the acceleration data on X,Y,Z
-    axis and supports 400, 100, 40 Hz sample frequency.
-
-Free fall Mode:
-    This mode is intended to save system resources.
-
-Threshold values:
-    Chip supports defining threshold values for above modes
-    which includes time and g value. Refer product specifications for
-    more details.
-
-CMA3000 chip supports mutually exclusive I2C and SPI interfaces for
-communication, currently the driver supports I2C based communication only.
-Initial configuration for bus mode is set in non volatile memory and can later
-be modified through bus interface command.
-
-Driver reports acceleration data through input subsystem. It generates ABS_MISC
-event with value 1 when free fall is detected.
-
-Platform data need to be configured for initial default values.
-
-Platform Data
--------------
-
-fuzz_x:
-    Noise on X Axis
-
-fuzz_y:
-    Noise on Y Axis
-
-fuzz_z:
-    Noise on Z Axis
-
-g_range:
-    G range in milli g i.e 2000 or 8000
-
-mode:
-    Default Operating mode
-
-mdthr:
-    Motion detect g range threshold value
-
-mdfftmr:
-    Motion detect and free fall time threshold value
-
-ffthr:
-    Free fall g range threshold value
-
-Input Interface
----------------
-
-Input driver version is 1.0.0
-Input device ID: bus 0x18 vendor 0x0 product 0x0 version 0x0
-Input device name: "cma3000-accelerometer"
-
-Supported events::
-
-  Event type 0 (Sync)
-  Event type 3 (Absolute)
-    Event code 0 (X)
-      Value     47
-      Min    -8000
-      Max     8000
-      Fuzz     200
-    Event code 1 (Y)
-      Value    -28
-      Min    -8000
-      Max     8000
-      Fuzz     200
-    Event code 2 (Z)
-      Value    905
-      Min    -8000
-      Max     8000
-      Fuzz     200
-    Event code 40 (Misc)
-      Value      0
-      Min        0
-      Max        1
-  Event type 4 (Misc)
-
-
-Register/Platform parameters Description
-----------------------------------------
-
-mode::
-
-       0: power down mode
-       1: 100 Hz Measurement mode
-       2: 400 Hz Measurement mode
-       3: 40 Hz Measurement mode
-       4: Motion Detect mode (default)
-       5: 100 Hz Free fall mode
-       6: 40 Hz Free fall mode
-       7: Power off mode
-
-grange::
-
-       2000: 2000 mg or 2G Range
-       8000: 8000 mg or 8G Range
-
-mdthr::
-
-       X: X * 71mg (8G Range)
-       X: X * 18mg (2G Range)
-
-mdfftmr::
-
-       X: (X & 0x70) * 100 ms (MDTMR)
-          (X & 0x0F) * 2.5 ms (FFTMR 400 Hz)
-          (X & 0x0F) * 10 ms  (FFTMR 100 Hz)
-
-ffthr::
-
-       X: (X >> 2) * 18mg (2G Range)
-       X: (X & 0x0F) * 71 mg (8G Range)
diff --git a/Documentation/input/cs461x.rst b/Documentation/input/cs461x.rst
deleted file mode 100644 (file)
index 1450436..0000000
+++ /dev/null
@@ -1,49 +0,0 @@
-Crystal SoundFusion CS4610/CS4612/CS461 joystick
-================================================
-
-Preface
--------
-
-This is a new low-level driver to support analog joystick attached to
-Crystal SoundFusion CS4610/CS4612/CS4615. This code is based upon
-Vortex/Solo drivers as an example of decoration style, and ALSA
-0.5.8a kernel drivers as an chipset documentation and samples.
-
-This version does not have cooked mode support; the basic code
-is present here, but have not tested completely. The button analysis
-is completed in this mode, but the axis movement is not.
-
-Raw mode works fine with analog joystick front-end driver and cs461x
-driver as a backend. I've tested this driver with CS4610, 4-axis and
-4-button joystick; I mean the jstest utility. Also I've tried to
-play in xracer game using joystick, and the result is better than
-keyboard only mode.
-
-The sensitivity and calibrate quality have not been tested; the two
-reasons are performed: the same hardware cannot work under Win95 (blue
-screen in VJOYD); I have no documentation on my chip; and the existing
-behavior in my case was not raised the requirement of joystick calibration.
-So the driver have no code to perform hardware related calibration.
-
-The patch contains minor changes of Config.in and Makefile files. All
-needed code have been moved to one separate file cs461x.c like ns558.c
-This driver have the basic support for PCI devices only; there is no
-ISA or PnP ISA cards supported. AFAIK the ns558 have support for Crystal
-ISA and PnP ISA series.
-
-The driver works with ALSA drivers simultaneously. For example, the xracer
-uses joystick as input device and PCM device as sound output in one time.
-There are no sound or input collisions detected. The source code have
-comments about them; but I've found the joystick can be initialized
-separately of ALSA modules. So, you can use only one joystick driver
-without ALSA drivers. The ALSA drivers are not needed to compile or
-run this driver.
-
-There are no debug information print have been placed in source, and no
-specific options required to work this driver. The found chipset parameters
-are printed via printk(KERN_INFO "..."), see the /var/log/messages to
-inspect cs461x: prefixed messages to determine possible card detection
-errors.
-
-Regards,
-Viktor
diff --git a/Documentation/input/devices/alps.rst b/Documentation/input/devices/alps.rst
new file mode 100644 (file)
index 0000000..6779148
--- /dev/null
@@ -0,0 +1,387 @@
+----------------------
+ALPS Touchpad Protocol
+----------------------
+
+Introduction
+------------
+Currently the ALPS touchpad driver supports seven protocol versions in use by
+ALPS touchpads, called versions 1, 2, 3, 4, 5, 6, 7 and 8.
+
+Since roughly mid-2010 several new ALPS touchpads have been released and
+integrated into a variety of laptops and netbooks.  These new touchpads
+have enough behavior differences that the alps_model_data definition
+table, describing the properties of the different versions, is no longer
+adequate.  The design choices were to re-define the alps_model_data
+table, with the risk of regression testing existing devices, or isolate
+the new devices outside of the alps_model_data table.  The latter design
+choice was made.  The new touchpad signatures are named: "Rushmore",
+"Pinnacle", and "Dolphin", which you will see in the alps.c code.
+For the purposes of this document, this group of ALPS touchpads will
+generically be called "new ALPS touchpads".
+
+We experimented with probing the ACPI interface _HID (Hardware ID)/_CID
+(Compatibility ID) definition as a way to uniquely identify the
+different ALPS variants but there did not appear to be a 1:1 mapping.
+In fact, it appeared to be an m:n mapping between the _HID and actual
+hardware type.
+
+Detection
+---------
+
+All ALPS touchpads should respond to the "E6 report" command sequence:
+E8-E6-E6-E6-E9. An ALPS touchpad should respond with either 00-00-0A or
+00-00-64 if no buttons are pressed. The bits 0-2 of the first byte will be 1s
+if some buttons are pressed.
+
+If the E6 report is successful, the touchpad model is identified using the "E7
+report" sequence: E8-E7-E7-E7-E9. The response is the model signature and is
+matched against known models in the alps_model_data_array.
+
+For older touchpads supporting protocol versions 3 and 4, the E7 report
+model signature is always 73-02-64. To differentiate between these
+versions, the response from the "Enter Command Mode" sequence must be
+inspected as described below.
+
+The new ALPS touchpads have an E7 signature of 73-03-50 or 73-03-0A but
+seem to be better differentiated by the EC Command Mode response.
+
+Command Mode
+------------
+
+Protocol versions 3 and 4 have a command mode that is used to read and write
+one-byte device registers in a 16-bit address space. The command sequence
+EC-EC-EC-E9 places the device in command mode, and the device will respond
+with 88-07 followed by a third byte. This third byte can be used to determine
+whether the devices uses the version 3 or 4 protocol.
+
+To exit command mode, PSMOUSE_CMD_SETSTREAM (EA) is sent to the touchpad.
+
+While in command mode, register addresses can be set by first sending a
+specific command, either EC for v3 devices or F5 for v4 devices. Then the
+address is sent one nibble at a time, where each nibble is encoded as a
+command with optional data. This encoding differs slightly between the v3 and
+v4 protocols.
+
+Once an address has been set, the addressed register can be read by sending
+PSMOUSE_CMD_GETINFO (E9). The first two bytes of the response contains the
+address of the register being read, and the third contains the value of the
+register. Registers are written by writing the value one nibble at a time
+using the same encoding used for addresses.
+
+For the new ALPS touchpads, the EC command is used to enter command
+mode. The response in the new ALPS touchpads is significantly different,
+and more important in determining the behavior.  This code has been
+separated from the original alps_model_data table and put in the
+alps_identify function.  For example, there seem to be two hardware init
+sequences for the "Dolphin" touchpads as determined by the second byte
+of the EC response.
+
+Packet Format
+-------------
+
+In the following tables, the following notation is used::
+
+ CAPITALS = stick, miniscules = touchpad
+
+?'s can have different meanings on different models, such as wheel rotation,
+extra buttons, stick buttons on a dualpoint, etc.
+
+PS/2 packet format
+------------------
+
+::
+
+ byte 0:  0    0 YSGN XSGN    1    M    R    L
+ byte 1: X7   X6   X5   X4   X3   X2   X1   X0
+ byte 2: Y7   Y6   Y5   Y4   Y3   Y2   Y1   Y0
+
+Note that the device never signals overflow condition.
+
+For protocol version 2 devices when the trackpoint is used, and no fingers
+are on the touchpad, the M R L bits signal the combined status of both the
+pointingstick and touchpad buttons.
+
+ALPS Absolute Mode - Protocol Version 1
+---------------------------------------
+
+::
+
+ byte 0:  1    0    0    0    1   x9   x8   x7
+ byte 1:  0   x6   x5   x4   x3   x2   x1   x0
+ byte 2:  0    ?    ?    l    r    ?  fin  ges
+ byte 3:  0    ?    ?    ?    ?   y9   y8   y7
+ byte 4:  0   y6   y5   y4   y3   y2   y1   y0
+ byte 5:  0   z6   z5   z4   z3   z2   z1   z0
+
+ALPS Absolute Mode - Protocol Version 2
+---------------------------------------
+
+::
+
+ byte 0:  1    ?    ?    ?    1  PSM  PSR  PSL
+ byte 1:  0   x6   x5   x4   x3   x2   x1   x0
+ byte 2:  0  x10   x9   x8   x7    ?  fin  ges
+ byte 3:  0   y9   y8   y7    1    M    R    L
+ byte 4:  0   y6   y5   y4   y3   y2   y1   y0
+ byte 5:  0   z6   z5   z4   z3   z2   z1   z0
+
+Protocol Version 2 DualPoint devices send standard PS/2 mouse packets for
+the DualPoint Stick. The M, R and L bits signal the combined status of both
+the pointingstick and touchpad buttons, except for Dell dualpoint devices
+where the pointingstick buttons get reported separately in the PSM, PSR
+and PSL bits.
+
+Dualpoint device -- interleaved packet format
+---------------------------------------------
+
+::
+
+ byte 0:    1    1    0    0    1    1    1    1
+ byte 1:    0   x6   x5   x4   x3   x2   x1   x0
+ byte 2:    0  x10   x9   x8   x7    0  fin  ges
+ byte 3:    0    0 YSGN XSGN    1    1    1    1
+ byte 4:   X7   X6   X5   X4   X3   X2   X1   X0
+ byte 5:   Y7   Y6   Y5   Y4   Y3   Y2   Y1   Y0
+ byte 6:    0   y9   y8   y7    1    m    r    l
+ byte 7:    0   y6   y5   y4   y3   y2   y1   y0
+ byte 8:    0   z6   z5   z4   z3   z2   z1   z0
+
+Devices which use the interleaving format normally send standard PS/2 mouse
+packets for the DualPoint Stick + ALPS Absolute Mode packets for the
+touchpad, switching to the interleaved packet format when both the stick and
+the touchpad are used at the same time.
+
+ALPS Absolute Mode - Protocol Version 3
+---------------------------------------
+
+ALPS protocol version 3 has three different packet formats. The first two are
+associated with touchpad events, and the third is associated with trackstick
+events.
+
+The first type is the touchpad position packet::
+
+ byte 0:    1    ?   x1   x0    1    1    1    1
+ byte 1:    0  x10   x9   x8   x7   x6   x5   x4
+ byte 2:    0  y10   y9   y8   y7   y6   y5   y4
+ byte 3:    0    M    R    L    1    m    r    l
+ byte 4:    0   mt   x3   x2   y3   y2   y1   y0
+ byte 5:    0   z6   z5   z4   z3   z2   z1   z0
+
+Note that for some devices the trackstick buttons are reported in this packet,
+and on others it is reported in the trackstick packets.
+
+The second packet type contains bitmaps representing the x and y axes. In the
+bitmaps a given bit is set if there is a finger covering that position on the
+given axis. Thus the bitmap packet can be used for low-resolution multi-touch
+data, although finger tracking is not possible.  This packet also encodes the
+number of contacts (f1 and f0 in the table below)::
+
+ byte 0:    1    1   x1   x0    1    1    1    1
+ byte 1:    0   x8   x7   x6   x5   x4   x3   x2
+ byte 2:    0   y7   y6   y5   y4   y3   y2   y1
+ byte 3:    0  y10   y9   y8    1    1    1    1
+ byte 4:    0  x14  x13  x12  x11  x10   x9   y0
+ byte 5:    0    1    ?    ?    ?    ?   f1   f0
+
+This packet only appears after a position packet with the mt bit set, and
+usually only appears when there are two or more contacts (although
+occasionally it's seen with only a single contact).
+
+The final v3 packet type is the trackstick packet::
+
+ byte 0:    1    1   x7   y7    1    1    1    1
+ byte 1:    0   x6   x5   x4   x3   x2   x1   x0
+ byte 2:    0   y6   y5   y4   y3   y2   y1   y0
+ byte 3:    0    1    0    0    1    0    0    0
+ byte 4:    0   z4   z3   z2   z1   z0    ?    ?
+ byte 5:    0    0    1    1    1    1    1    1
+
+ALPS Absolute Mode - Protocol Version 4
+---------------------------------------
+
+Protocol version 4 has an 8-byte packet format::
+
+ byte 0:    1    ?   x1   x0    1    1    1    1
+ byte 1:    0  x10   x9   x8   x7   x6   x5   x4
+ byte 2:    0  y10   y9   y8   y7   y6   y5   y4
+ byte 3:    0    1   x3   x2   y3   y2   y1   y0
+ byte 4:    0    ?    ?    ?    1    ?    r    l
+ byte 5:    0   z6   z5   z4   z3   z2   z1   z0
+ byte 6:    bitmap data (described below)
+ byte 7:    bitmap data (described below)
+
+The last two bytes represent a partial bitmap packet, with 3 full packets
+required to construct a complete bitmap packet.  Once assembled, the 6-byte
+bitmap packet has the following format::
+
+ byte 0:    0    1   x7   x6   x5   x4   x3   x2
+ byte 1:    0   x1   x0   y4   y3   y2   y1   y0
+ byte 2:    0    0    ?  x14  x13  x12  x11  x10
+ byte 3:    0   x9   x8   y9   y8   y7   y6   y5
+ byte 4:    0    0    0    0    0    0    0    0
+ byte 5:    0    0    0    0    0    0    0  y10
+
+There are several things worth noting here.
+
+ 1) In the bitmap data, bit 6 of byte 0 serves as a sync byte to
+    identify the first fragment of a bitmap packet.
+
+ 2) The bitmaps represent the same data as in the v3 bitmap packets, although
+    the packet layout is different.
+
+ 3) There doesn't seem to be a count of the contact points anywhere in the v4
+    protocol packets. Deriving a count of contact points must be done by
+    analyzing the bitmaps.
+
+ 4) There is a 3 to 1 ratio of position packets to bitmap packets. Therefore
+    MT position can only be updated for every third ST position update, and
+    the count of contact points can only be updated every third packet as
+    well.
+
+So far no v4 devices with tracksticks have been encountered.
+
+ALPS Absolute Mode - Protocol Version 5
+---------------------------------------
+This is basically Protocol Version 3 but with different logic for packet
+decode.  It uses the same alps_process_touchpad_packet_v3 call with a
+specialized decode_fields function pointer to correctly interpret the
+packets.  This appears to only be used by the Dolphin devices.
+
+For single-touch, the 6-byte packet format is::
+
+ byte 0:    1    1    0    0    1    0    0    0
+ byte 1:    0   x6   x5   x4   x3   x2   x1   x0
+ byte 2:    0   y6   y5   y4   y3   y2   y1   y0
+ byte 3:    0    M    R    L    1    m    r    l
+ byte 4:   y10  y9   y8   y7  x10   x9   x8   x7
+ byte 5:    0   z6   z5   z4   z3   z2   z1   z0
+
+For mt, the format is::
+
+ byte 0:    1    1    1    n3   1   n2   n1   x24
+ byte 1:    1   y7   y6    y5  y4   y3   y2    y1
+ byte 2:    ?   x2   x1   y12 y11  y10   y9    y8
+ byte 3:    0  x23  x22   x21 x20  x19  x18   x17
+ byte 4:    0   x9   x8    x7  x6   x5   x4    x3
+ byte 5:    0  x16  x15   x14 x13  x12  x11   x10
+
+ALPS Absolute Mode - Protocol Version 6
+---------------------------------------
+
+For trackstick packet, the format is::
+
+ byte 0:    1    1    1    1    1    1    1    1
+ byte 1:    0   X6   X5   X4   X3   X2   X1   X0
+ byte 2:    0   Y6   Y5   Y4   Y3   Y2   Y1   Y0
+ byte 3:    ?   Y7   X7    ?    ?    M    R    L
+ byte 4:   Z7   Z6   Z5   Z4   Z3   Z2   Z1   Z0
+ byte 5:    0    1    1    1    1    1    1    1
+
+For touchpad packet, the format is::
+
+ byte 0:    1    1    1    1    1    1    1    1
+ byte 1:    0    0    0    0   x3   x2   x1   x0
+ byte 2:    0    0    0    0   y3   y2   y1   y0
+ byte 3:    ?   x7   x6   x5   x4    ?    r    l
+ byte 4:    ?   y7   y6   y5   y4    ?    ?    ?
+ byte 5:   z7   z6   z5   z4   z3   z2   z1   z0
+
+(v6 touchpad does not have middle button)
+
+ALPS Absolute Mode - Protocol Version 7
+---------------------------------------
+
+For trackstick packet, the format is::
+
+ byte 0:    0    1    0    0    1    0    0    0
+ byte 1:    1    1    *    *    1    M    R    L
+ byte 2:   X7    1   X5   X4   X3   X2   X1   X0
+ byte 3:   Z6    1   Y6   X6    1   Y2   Y1   Y0
+ byte 4:   Y7    0   Y5   Y4   Y3    1    1    0
+ byte 5:  T&P    0   Z5   Z4   Z3   Z2   Z1   Z0
+
+For touchpad packet, the format is::
+
+         packet-fmt     b7     b6     b5     b4     b3     b2     b1     b0
+ byte 0: TWO & MULTI     L      1      R      M      1   Y0-2   Y0-1   Y0-0
+ byte 0: NEW             L      1   X1-5      1      1   Y0-2   Y0-1   Y0-0
+ byte 1:             Y0-10   Y0-9   Y0-8   Y0-7   Y0-6   Y0-5   Y0-4   Y0-3
+ byte 2:             X0-11      1  X0-10   X0-9   X0-8   X0-7   X0-6   X0-5
+ byte 3:             X1-11      1   X0-4   X0-3      1   X0-2   X0-1   X0-0
+ byte 4: TWO         X1-10    TWO   X1-9   X1-8   X1-7   X1-6   X1-5   X1-4
+ byte 4: MULTI       X1-10    TWO   X1-9   X1-8   X1-7   X1-6   Y1-5      1
+ byte 4: NEW         X1-10    TWO   X1-9   X1-8   X1-7   X1-6      0      0
+ byte 5: TWO & NEW   Y1-10      0   Y1-9   Y1-8   Y1-7   Y1-6   Y1-5   Y1-4
+ byte 5: MULTI       Y1-10      0   Y1-9   Y1-8   Y1-7   Y1-6    F-1    F-0
+
+ L:         Left button
+ R / M:     Non-clickpads: Right / Middle button
+            Clickpads: When > 2 fingers are down, and some fingers
+            are in the button area, then the 2 coordinates reported
+            are for fingers outside the button area and these report
+            extra fingers being present in the right / left button
+            area. Note these fingers are not added to the F field!
+            so if a TWO packet is received and R = 1 then there are
+            3 fingers down, etc.
+ TWO:       1: Two touches present, byte 0/4/5 are in TWO fmt
+            0: If byte 4 bit 0 is 1, then byte 0/4/5 are in MULTI fmt
+               otherwise byte 0 bit 4 must be set and byte 0/4/5 are
+               in NEW fmt
+ F:         Number of fingers - 3, 0 means 3 fingers, 1 means 4 ...
+
+
+ALPS Absolute Mode - Protocol Version 8
+---------------------------------------
+
+Spoken by SS4 (73 03 14) and SS5 (73 03 28) hardware.
+
+The packet type is given by the APD field, bits 4-5 of byte 3.
+
+Touchpad packet (APD = 0x2)::
+
+           b7   b6   b5   b4   b3   b2   b1   b0
+ byte 0:  SWM  SWR  SWL    1    1    0    0   X7
+ byte 1:    0   X6   X5   X4   X3   X2   X1   X0
+ byte 2:    0   Y6   Y5   Y4   Y3   Y2   Y1   Y0
+ byte 3:    0  T&P    1    0    1    0    0   Y7
+ byte 4:    0   Z6   Z5   Z4   Z3   Z2   Z1   Z0
+ byte 5:    0    0    0    0    0    0    0    0
+
+SWM, SWR, SWL: Middle, Right, and Left button states
+
+Touchpad 1 Finger packet (APD = 0x0)::
+
+           b7   b6   b5   b4   b3   b2   b1   b0
+ byte 0:  SWM  SWR  SWL    1    1   X2   X1   X0
+ byte 1:   X9   X8   X7    1   X6   X5   X4   X3
+ byte 2:    0  X11  X10  LFB   Y3   Y2   Y1   Y0
+ byte 3:   Y5   Y4    0    0    1 TAPF2 TAPF1 TAPF0
+ byte 4:  Zv7  Y11  Y10    1   Y9   Y8   Y7   Y6
+ byte 5:  Zv6  Zv5  Zv4    0  Zv3  Zv2  Zv1  Zv0
+
+TAPF: ???
+LFB:  ???
+
+Touchpad 2 Finger packet (APD = 0x1)::
+
+           b7   b6   b5   b4   b3   b2   b1   b0
+ byte 0:  SWM  SWR  SWL    1    1  AX6  AX5  AX4
+ byte 1: AX11 AX10  AX9  AX8  AX7  AZ1  AY4  AZ0
+ byte 2: AY11 AY10  AY9  CONT AY8  AY7  AY6  AY5
+ byte 3:    0    0    0    1    1  BX6  BX5  BX4
+ byte 4: BX11 BX10  BX9  BX8  BX7  BZ1  BY4  BZ0
+ byte 5: BY11 BY10  BY9    0  BY8  BY7  BY5  BY5
+
+CONT: A 3-or-4 Finger packet is to follow
+
+Touchpad 3-or-4 Finger packet (APD = 0x3)::
+
+           b7   b6   b5   b4   b3   b2   b1   b0
+ byte 0:  SWM  SWR  SWL    1    1  AX6  AX5  AX4
+ byte 1: AX11 AX10  AX9  AX8  AX7  AZ1  AY4  AZ0
+ byte 2: AY11 AY10  AY9  OVF  AY8  AY7  AY6  AY5
+ byte 3:    0    0    1    1    1  BX6  BX5  BX4
+ byte 4: BX11 BX10  BX9  BX8  BX7  BZ1  BY4  BZ0
+ byte 5: BY11 BY10  BY9    0  BY8  BY7  BY5  BY5
+
+OVF: 5th finger detected
diff --git a/Documentation/input/devices/amijoy.rst b/Documentation/input/devices/amijoy.rst
new file mode 100644 (file)
index 0000000..8df7b11
--- /dev/null
@@ -0,0 +1,263 @@
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Amiga joystick extensions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+Amiga 4-joystick parport extension
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Parallel port pins:
+
+
+=====  ======== ====   ==========
+Pin    Meaning  Pin    Meaning
+=====  ======== ====   ==========
+ 2     Up1      6     Up2
+ 3     Down1    7     Down2
+ 4     Left1    8     Left2
+ 5     Right1   9     Right2
+13     Fire1   11     Fire2
+18     Gnd1    18     Gnd2
+=====  ======== ====   ==========
+
+Amiga digital joystick pinout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+=== ============
+Pin Meaning
+=== ============
+1   Up
+2   Down
+3   Left
+4   Right
+5   n/c
+6   Fire button
+7   +5V (50mA)
+8   Gnd
+9   Thumb button
+=== ============
+
+Amiga mouse pinout
+~~~~~~~~~~~~~~~~~~
+
+=== ============
+Pin Meaning
+=== ============
+1   V-pulse
+2   H-pulse
+3   VQ-pulse
+4   HQ-pulse
+5   Middle button
+6   Left button
+7   +5V (50mA)
+8   Gnd
+9   Right button
+=== ============
+
+Amiga analog joystick pinout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+=== ==============
+Pin Meaning
+=== ==============
+1   Top button
+2   Top2 button
+3   Trigger button
+4   Thumb button
+5   Analog X
+6   n/c
+7   +5V (50mA)
+8   Gnd
+9   Analog Y
+=== ==============
+
+Amiga lightpen pinout
+~~~~~~~~~~~~~~~~~~~~~
+
+=== =============
+Pin Meaning
+=== =============
+1   n/c
+2   n/c
+3   n/c
+4   n/c
+5   Touch button
+6   /Beamtrigger
+7   +5V (50mA)
+8   Gnd
+9   Stylus button
+=== =============
+
+-------------------------------------------------------------------------------
+
+======== === ==== ==== ====== ========================================
+NAME     rev ADDR type chip   Description
+======== === ==== ==== ====== ========================================
+JOY0DAT      00A   R   Denise Joystick-mouse 0 data (left vert, horiz)
+JOY1DAT      00C   R   Denise Joystick-mouse 1 data (right vert,horiz)
+======== === ==== ==== ====== ========================================
+
+        These addresses each read a 16 bit register. These in turn
+        are loaded from the MDAT serial stream and are clocked in on
+        the rising edge of SCLK. MLD output is used to parallel load
+        the external parallel-to-serial converter.This in turn is
+        loaded with the 4 quadrature inputs from each of two game
+        controller ports (8 total) plus 8 miscellaneous control bits
+        which are new for LISA and can be read in upper 8 bits of
+        LISAID.
+
+        Register bits are as follows:
+
+        - Mouse counter usage (pins  1,3 =Yclock, pins 2,4 =Xclock)
+
+======== === === === === === === === === ====== === === === === === === ===
+    BIT#  15  14  13  12  11  10  09  08     07  06  05  04  03  02  01  00
+======== === === === === === === === === ====== === === === === === === ===
+JOY0DAT   Y7  Y6  Y5  Y4  Y3  Y2  Y1  Y0     X7  X6  X5  X4  X3  X2  X1  X0
+JOY1DAT   Y7  Y6  Y5  Y4  Y3  Y2  Y1  Y0     X7  X6  X5  X4  X3  X2  X1  X0
+======== === === === === === === === === ====== === === === === === === ===
+
+        0=LEFT CONTROLLER PAIR, 1=RIGHT CONTROLLER PAIR.
+        (4 counters total). The bit usage for both left and right
+        addresses is shown below. Each 6 bit counter (Y7-Y2,X7-X2) is
+        clocked by 2 of the signals input from the mouse serial
+        stream. Starting with first bit received:
+
+         +-------------------+-----------------------------------------+
+         | Serial | Bit Name | Description                             |
+         +========+==========+=========================================+
+         |   0    | M0H      | JOY0DAT Horizontal Clock                |
+         +--------+----------+-----------------------------------------+
+         |   1    | M0HQ     | JOY0DAT Horizontal Clock (quadrature)   |
+         +--------+----------+-----------------------------------------+
+         |   2    | M0V      | JOY0DAT Vertical Clock                  |
+         +--------+----------+-----------------------------------------+
+         |   3    | M0VQ     | JOY0DAT Vertical Clock  (quadrature)    |
+         +--------+----------+-----------------------------------------+
+         |   4    | M1V      | JOY1DAT Horizontal Clock                |
+         +--------+----------+-----------------------------------------+
+         |   5    | M1VQ     | JOY1DAT Horizontal Clock (quadrature)   |
+         +--------+----------+-----------------------------------------+
+         |   6    | M1V      | JOY1DAT Vertical Clock                  |
+         +--------+----------+-----------------------------------------+
+         |   7    | M1VQ     | JOY1DAT Vertical Clock (quadrature)     |
+         +--------+----------+-----------------------------------------+
+
+         Bits 1 and 0 of each counter (Y1-Y0,X1-X0) may be
+         read to determine the state of the related input signal pair.
+         This allows these pins to double as joystick switch inputs.
+         Joystick switch closures can be deciphered as follows:
+
+         +------------+------+---------------------------------+
+         | Directions | Pin# | Counter bits                    |
+         +============+======+=================================+
+         | Forward    |  1   | Y1 xor Y0 (BIT#09 xor BIT#08)   |
+         +------------+------+---------------------------------+
+         | Left       |  3   | Y1                              |
+         +------------+------+---------------------------------+
+         | Back       |  2   | X1 xor X0 (BIT#01 xor BIT#00)   |
+         +------------+------+---------------------------------+
+         | Right      |  4   | X1                              |
+         +------------+------+---------------------------------+
+
+-------------------------------------------------------------------------------
+
+========  === ==== ==== ====== =================================================
+NAME      rev ADDR type chip    Description
+========  === ==== ==== ====== =================================================
+JOYTEST       036   W   Denise  Write to all 4  joystick-mouse counters at once.
+========  === ==== ==== ====== =================================================
+
+                  Mouse counter write test data:
+
+========= === === === === === === === === ====== === === === === === === ===
+     BIT#  15  14  13  12  11  10  09  08     07  06  05  04  03  02  01  00
+========= === === === === === === === === ====== === === === === === === ===
+  JOYxDAT  Y7  Y6  Y5  Y4  Y3  Y2  xx  xx     X7  X6  X5  X4  X3  X2  xx  xx
+  JOYxDAT  Y7  Y6  Y5  Y4  Y3  Y2  xx  xx     X7  X6  X5  X4  X3  X2  xx  xx
+========= === === === === === === === === ====== === === === === === === ===
+
+-------------------------------------------------------------------------------
+
+======= === ==== ==== ====== ========================================
+NAME    rev ADDR type chip   Description
+======= === ==== ==== ====== ========================================
+POT0DAT  h  012   R   Paula  Pot counter data left pair (vert, horiz)
+POT1DAT  h  014   R   Paula  Pot counter data right pair (vert,horiz)
+======= === ==== ==== ====== ========================================
+
+        These addresses each read a pair of 8 bit pot counters.
+        (4 counters total). The bit assignment for both
+        addresses is shown below. The counters are stopped by signals
+        from 2 controller connectors (left-right) with 2 pins each.
+
+====== === === === === === === === === ====== === === === === === === ===
+  BIT#  15  14  13  12  11  10  09  08     07  06  05  04  03  02  01  00
+====== === === === === === === === === ====== === === === === === === ===
+ RIGHT  Y7  Y6  Y5  Y4  Y3  Y2  Y1  Y0     X7  X6  X5  X4  X3  X2  X1  X0
+  LEFT  Y7  Y6  Y5  Y4  Y3  Y2  Y1  Y0     X7  X6  X5  X4  X3  X2  X1  X0
+====== === === === === === === === === ====== === === === === === === ===
+
+         +--------------------------+-------+
+         | CONNECTORS               | PAULA |
+         +-------+------+-----+-----+-------+
+         | Loc.  | Dir. | Sym | pin | pin   |
+         +=======+======+=====+=====+=======+
+         | RIGHT | Y    | RX  | 9   | 33    |
+         +-------+------+-----+-----+-------+
+         | RIGHT | X    | RX  | 5   | 32    |
+         +-------+------+-----+-----+-------+
+         | LEFT  | Y    | LY  | 9   | 36    |
+         +-------+------+-----+-----+-------+
+         | LEFT  | X    | LX  | 5   | 35    |
+         +-------+------+-----+-----+-------+
+
+         With normal (NTSC or PAL) horiz. line rate, the pots will
+         give a full scale (FF) reading with about 500kohms in one
+         frame time. With proportionally faster horiz line times,
+         the counters will count proportionally faster.
+         This should be noted when doing variable beam displays.
+
+-------------------------------------------------------------------------------
+
+====== === ==== ==== ====== ================================================
+NAME   rev ADDR type chip   Description
+====== === ==== ==== ====== ================================================
+POTGO      034   W   Paula  Pot port (4 bit) bi-direction and data, and pot
+                           counter start.
+====== === ==== ==== ====== ================================================
+
+-------------------------------------------------------------------------------
+
+====== === ==== ==== ====== ================================================
+NAME   rev ADDR type chip   Description
+====== === ==== ==== ====== ================================================
+POTINP     016   R   Paula  Pot pin data read
+====== === ==== ==== ====== ================================================
+
+        This register controls a 4 bit bi-direction I/O port
+        that shares the same 4 pins as the 4 pot counters above.
+
+         +-------+----------+---------------------------------------------+
+         | BIT#  | FUNCTION | DESCRIPTION                                 |
+         +=======+==========+=============================================+
+         | 15    | OUTRY    | Output enable for Paula pin 33              |
+         +-------+----------+---------------------------------------------+
+         | 14    | DATRY    | I/O data Paula pin 33                       |
+         +-------+----------+---------------------------------------------+
+         | 13    | OUTRX    | Output enable for Paula pin 32              |
+         +-------+----------+---------------------------------------------+
+         | 12    | DATRX    | I/O data Paula pin 32                       |
+         +-------+----------+---------------------------------------------+
+         | 11    | OUTLY    | Out put enable for Paula pin 36             |
+         +-------+----------+---------------------------------------------+
+         | 10    | DATLY    | I/O data Paula pin 36                       |
+         +-------+----------+---------------------------------------------+
+         | 09    | OUTLX    | Output enable for Paula pin 35              |
+         +-------+----------+---------------------------------------------+
+         | 08    | DATLX    | I/O data  Paula pin 35                      |
+         +-------+----------+---------------------------------------------+
+         | 07-01 |   X      | Not used                                    |
+         +-------+----------+---------------------------------------------+
+         | 00    | START    | Start pots (dump capacitors,start counters) |
+         +-------+----------+---------------------------------------------+
diff --git a/Documentation/input/devices/appletouch.rst b/Documentation/input/devices/appletouch.rst
new file mode 100644 (file)
index 0000000..c94470e
--- /dev/null
@@ -0,0 +1,94 @@
+.. include:: <isonum.txt>
+
+----------------------------------
+Apple Touchpad Driver (appletouch)
+----------------------------------
+
+:Copyright: |copy| 2005 Stelian Pop <stelian@popies.net>
+
+appletouch is a Linux kernel driver for the USB touchpad found on post
+February 2005 and October 2005 Apple Aluminium Powerbooks.
+
+This driver is derived from Johannes Berg's appletrackpad driver [#f1]_,
+but it has been improved in some areas:
+
+       * appletouch is a full kernel driver, no userspace program is necessary
+       * appletouch can be interfaced with the synaptics X11 driver, in order
+         to have touchpad acceleration, scrolling, etc.
+
+Credits go to Johannes Berg for reverse-engineering the touchpad protocol,
+Frank Arnold for further improvements, and Alex Harper for some additional
+information about the inner workings of the touchpad sensors. Michael
+Hanselmann added support for the October 2005 models.
+
+Usage
+-----
+
+In order to use the touchpad in the basic mode, compile the driver and load
+the module. A new input device will be detected and you will be able to read
+the mouse data from /dev/input/mice (using gpm, or X11).
+
+In X11, you can configure the touchpad to use the synaptics X11 driver, which
+will give additional functionalities, like acceleration, scrolling, 2 finger
+tap for middle button mouse emulation, 3 finger tap for right button mouse
+emulation, etc. In order to do this, make sure you're using a recent version of
+the synaptics driver (tested with 0.14.2, available from [#f2]_), and configure
+a new input device in your X11 configuration file (take a look below for an
+example). For additional configuration, see the synaptics driver documentation::
+
+       Section "InputDevice"
+               Identifier      "Synaptics Touchpad"
+               Driver          "synaptics"
+               Option          "SendCoreEvents"        "true"
+               Option          "Device"                "/dev/input/mice"
+               Option          "Protocol"              "auto-dev"
+               Option          "LeftEdge"              "0"
+               Option          "RightEdge"             "850"
+               Option          "TopEdge"               "0"
+               Option          "BottomEdge"            "645"
+               Option          "MinSpeed"              "0.4"
+               Option          "MaxSpeed"              "1"
+               Option          "AccelFactor"           "0.02"
+               Option          "FingerLow"             "0"
+               Option          "FingerHigh"            "30"
+               Option          "MaxTapMove"            "20"
+               Option          "MaxTapTime"            "100"
+               Option          "HorizScrollDelta"      "0"
+               Option          "VertScrollDelta"       "30"
+               Option          "SHMConfig"             "on"
+       EndSection
+
+       Section "ServerLayout"
+               ...
+               InputDevice     "Mouse"
+               InputDevice     "Synaptics Touchpad"
+       ...
+       EndSection
+
+Fuzz problems
+-------------
+
+The touchpad sensors are very sensitive to heat, and will generate a lot of
+noise when the temperature changes. This is especially true when you power-on
+the laptop for the first time.
+
+The appletouch driver tries to handle this noise and auto adapt itself, but it
+is not perfect. If finger movements are not recognized anymore, try reloading
+the driver.
+
+You can activate debugging using the 'debug' module parameter. A value of 0
+deactivates any debugging, 1 activates tracing of invalid samples, 2 activates
+full tracing (each sample is being traced)::
+
+       modprobe appletouch debug=1
+
+or::
+
+       echo "1" > /sys/module/appletouch/parameters/debug
+
+
+.. Links:
+
+.. [#f1] http://johannes.sipsolutions.net/PowerBook/touchpad/
+
+.. [#f2] `<http://web.archive.org/web/*/http://web.telia.com/~u89404340/touchpad/index.html>`_
diff --git a/Documentation/input/devices/atarikbd.rst b/Documentation/input/devices/atarikbd.rst
new file mode 100644 (file)
index 0000000..745e7a1
--- /dev/null
@@ -0,0 +1,820 @@
+====================================
+Intelligent Keyboard (ikbd) Protocol
+====================================
+
+
+Introduction
+============
+
+The Atari Corp. Intelligent Keyboard (ikbd) is a general purpose keyboard
+controller that is flexible enough that it can be used in a variety of
+products without modification. The keyboard, with its microcontroller,
+provides a convenient connection point for a mouse and switch-type joysticks.
+The ikbd processor also maintains a time-of-day clock with one second
+resolution.
+The ikbd has been designed to be general enough that it can be used with a
+variety of new computer products. Product variations in a number of
+keyswitches, mouse resolution, etc. can be accommodated.
+The ikbd communicates with the main processor over a high speed bi-directional
+serial interface. It can function in a variety of modes to facilitate
+different applications of the keyboard,  joysticks, or mouse. Limited use of
+the controller is possible in applications in which only a unidirectional
+communications medium is available by carefully designing the default modes.
+
+Keyboard
+========
+
+The keyboard always returns key make/break scan codes. The ikbd generates
+keyboard scan codes for each key press and release. The key scan make (key
+closure) codes start at 1, and are defined in Appendix A. For example, the
+ISO key position in the scan code table should exist even if no keyswitch
+exists in that position on a particular keyboard. The break code for each key
+is obtained by ORing 0x80 with the make code.
+
+The special codes 0xF6 through 0xFF are reserved for use as follows:
+
+=================== ====================================================
+    Code            Command
+=================== ====================================================
+    0xF6            status report
+    0xF7            absolute mouse position record
+    0xF8-0xFB       relative mouse position records (lsbs determined by
+                    mouse button states)
+    0xFC            time-of-day
+    0xFD            joystick report (both sticks)
+    0xFE            joystick 0 event
+    0xFF            joystick 1 event
+=================== ====================================================
+
+The two shift keys return different scan codes in this mode. The ENTER key
+and the RETurn key are also distinct.
+
+Mouse
+=====
+
+The mouse port should be capable of supporting a mouse with resolution of
+approximately 200 counts (phase changes or 'clicks') per inch of travel. The
+mouse should be scanned at a rate that will permit accurate tracking at
+velocities up to 10 inches per second.
+The ikbd can report mouse motion in three distinctly different ways. It can
+report relative motion, absolute motion in a coordinate system maintained
+within the ikbd, or by converting mouse motion into keyboard cursor control
+key equivalents.
+The mouse buttons can be treated as part of the mouse or as additional
+keyboard keys.
+
+Relative Position Reporting
+---------------------------
+
+In relative position mode, the ikbd will return relative mouse position
+records whenever a mouse event occurs. A mouse event consists of a mouse
+button being pressed or released, or motion in either axis exceeding a
+settable threshold of motion. Regardless of the threshold, all bits of
+resolution are returned to the host computer.
+Note that the ikbd may return mouse relative position reports with
+significantly more than the threshold delta x or y. This may happen since no
+relative mouse motion events will be generated: (a) while the keyboard has
+been 'paused' ( the event will be stored until keyboard communications is
+resumed) (b) while any event is being transmitted.
+
+The relative mouse position record is a three byte record of the form
+(regardless of keyboard mode)::
+
+    %111110xy           ; mouse position record flag
+                        ; where y is the right button state
+                        ; and x is the left button state
+    X                   ; delta x as twos complement integer
+    Y                   ; delta y as twos complement integer
+
+Note that the value of the button state bits should be valid even if the
+MOUSE BUTTON ACTION has set the buttons to act like part of the keyboard.
+If the accumulated motion before the report packet is generated exceeds the
++127...-128 range, the motion is broken into multiple packets.
+Note that the sign of the delta y reported is a function of the Y origin
+selected.
+
+Absolute Position reporting
+---------------------------
+
+The ikbd can also maintain absolute mouse position. Commands exist for
+resetting the mouse position, setting X/Y scaling, and interrogating the
+current mouse position.
+
+Mouse Cursor Key Mode
+---------------------
+
+The ikbd can translate mouse motion into the equivalent cursor keystrokes.
+The number of mouse clicks per keystroke is independently programmable in
+each axis. The ikbd internally maintains mouse motion information to the
+highest resolution available, and merely generates a pair of cursor key events
+for each multiple of the scale factor.
+Mouse motion produces the cursor key make code immediately followed by the
+break code for the appropriate cursor key. The mouse buttons produce scan
+codes above those normally assigned for the largest envisioned keyboard (i.e.
+LEFT=0x74 & RIGHT=0x75).
+
+Joystick
+========
+
+Joystick Event Reporting
+------------------------
+
+In this mode, the ikbd generates a record whenever the joystick position is
+changed (i.e. for each opening or closing of a joystick switch or trigger).
+
+The joystick event record is two bytes of the form::
+
+    %1111111x           ; Joystick event marker
+                        ; where x is Joystick 0 or 1
+    %x000yyyy           ; where yyyy is the stick position
+                        ; and x is the trigger
+
+Joystick Interrogation
+----------------------
+
+The current state of the joystick ports may be interrogated at any time in
+this mode by sending an 'Interrogate Joystick' command to the ikbd.
+
+The ikbd response to joystick interrogation is a three byte report of the form::
+
+    0xFD                ; joystick report header
+    %x000yyyy           ; Joystick 0
+    %x000yyyy           ; Joystick 1
+                        ; where x is the trigger
+                        ; and yyy is the stick position
+
+Joystick Monitoring
+-------------------
+
+A mode is available that devotes nearly all of the keyboard communications
+time to reporting the state of the joystick ports at a user specifiable rate.
+It remains in this mode until reset or commanded into another mode. The PAUSE
+command in this mode not only stop the output but also temporarily stops
+scanning the joysticks (samples are not queued).
+
+Fire Button Monitoring
+----------------------
+
+A mode is provided to permit monitoring a single input bit at a high rate. In
+this mode the ikbd monitors the state of the Joystick 1 fire button at the
+maximum rate permitted by the serial communication channel. The data is packed
+8 bits per byte for transmission to the host. The ikbd remains in this mode
+until reset or commanded into another mode. The PAUSE command in this mode not
+only stops the output but also temporarily stops scanning the button (samples
+are not queued).
+
+Joystick Key Code Mode
+----------------------
+
+The ikbd may be commanded to translate the use of either joystick into the
+equivalent cursor control keystroke(s). The ikbd provides a single breakpoint
+velocity joystick cursor.
+Joystick events produce the make code, immediately followed by the break code
+for the appropriate cursor motion keys. The trigger or fire buttons of the
+joysticks produce pseudo key scan codes above those used by the largest key
+matrix envisioned (i.e. JOYSTICK0=0x74, JOYSTICK1=0x75).
+
+Time-of-Day Clock
+=================
+
+The ikbd also maintains a time-of-day clock for the system. Commands are
+available to set and interrogate the timer-of-day clock. Time-keeping is
+maintained down to a resolution of one second.
+
+Status Inquiries
+================
+
+The current state of ikbd modes and parameters may be found by sending status
+inquiry commands that correspond to the ikbd set commands.
+
+Power-Up Mode
+=============
+
+The keyboard controller will perform a simple self-test on power-up to detect
+major controller faults (ROM checksum and RAM test) and such things as stuck
+keys. Any keys down at power-up are presumed to be stuck, and their BREAK
+(sic) code is returned (which without the preceding MAKE code is a flag for a
+keyboard error). If the controller self-test completes without error, the code
+0xF0 is returned. (This code will be used to indicate the version/release of
+the ikbd controller. The first release of the ikbd is version 0xF0, should
+there be a second release it will be 0xF1, and so on.)
+The ikbd defaults to a mouse position reporting with threshold of 1 unit in
+either axis and the Y=0 origin at the top of the screen, and joystick event
+reporting mode for joystick 1, with both buttons being logically assigned to
+the mouse. After any joystick command, the ikbd assumes that joysticks are
+connected to both Joystick0 and Joystick1. Any mouse command (except MOUSE
+DISABLE) then causes port 0 to again be scanned as if it were a mouse, and
+both buttons are logically connected to it. If a mouse disable command is
+received while port 0 is presumed to be a mouse, the button is logically
+assigned to Joystick1 (until the mouse is reenabled by another mouse command).
+
+ikbd Command Set
+================
+
+This section contains a list of commands that can be sent to the ikbd. Command
+codes (such as 0x00) which are not specified should perform no operation
+(NOPs).
+
+RESET
+-----
+
+::
+
+    0x80
+    0x01
+
+N.B. The RESET command is the only two byte command understood by the ikbd.
+Any byte following an 0x80 command byte other than 0x01 is ignored (and causes
+the 0x80 to be ignored).
+A reset may also be caused by sending a break lasting at least 200mS to the
+ikbd.
+Executing the RESET command returns the keyboard to its default (power-up)
+mode and parameter settings. It does not affect the time-of-day clock.
+The RESET command or function causes the ikbd to perform a simple self-test.
+If the test is successful, the ikbd will send the code of 0xF0 within 300mS
+of receipt of the RESET command (or the end of the break, or power-up). The
+ikbd will then scan the key matrix for any stuck (closed) keys. Any keys found
+closed will cause the break scan code to be generated (the break code arriving
+without being preceded by the make code is a flag for a key matrix error).
+
+SET MOUSE BUTTON ACTION
+-----------------------
+
+::
+
+    0x07
+    %00000mss           ; mouse button action
+                        ;       (m is presumed = 1 when in MOUSE KEYCODE mode)
+                        ; mss=0xy, mouse button press or release causes mouse
+                        ;  position report
+                        ;  where y=1, mouse key press causes absolute report
+                        ;  and x=1, mouse key release causes absolute report
+                        ; mss=100, mouse buttons act like keys
+
+This command sets how the ikbd should treat the buttons on the mouse. The
+default mouse button action mode is %00000000, the buttons are treated as part
+of the mouse logically.
+When buttons act like keys, LEFT=0x74 & RIGHT=0x75.
+
+SET RELATIVE MOUSE POSITION REPORTING
+-------------------------------------
+
+::
+
+    0x08
+
+Set relative mouse position reporting. (DEFAULT) Mouse position packets are
+generated asynchronously by the ikbd whenever motion exceeds the setable
+threshold in either axis (see SET MOUSE THRESHOLD). Depending upon the mouse
+key mode, mouse position reports may also be generated when either mouse
+button is pressed or released. Otherwise the mouse buttons behave as if they
+were keyboard keys.
+
+SET ABSOLUTE MOUSE POSITIONING
+------------------------------
+
+::
+
+    0x09
+    XMSB                ; X maximum (in scaled mouse clicks)
+    XLSB
+    YMSB                ; Y maximum (in scaled mouse clicks)
+    YLSB
+
+Set absolute mouse position maintenance. Resets the ikbd maintained X and Y
+coordinates.
+In this mode, the value of the internally maintained coordinates does NOT wrap
+between 0 and large positive numbers. Excess motion below 0 is ignored. The
+command sets the maximum positive value that can be attained in the scaled
+coordinate system. Motion beyond that value is also ignored.
+
+SET MOUSE KEYCODE MOSE
+----------------------
+
+::
+
+    0x0A
+    deltax              ; distance in X clicks to return (LEFT) or (RIGHT)
+    deltay              ; distance in Y clicks to return (UP) or (DOWN)
+
+Set mouse monitoring routines to return cursor motion keycodes instead of
+either RELATIVE or ABSOLUTE motion records. The ikbd returns the appropriate
+cursor keycode after mouse travel exceeding the user specified deltas in
+either axis. When the keyboard is in key scan code mode, mouse motion will
+cause the make code immediately followed by the break code. Note that this
+command is not affected by the mouse motion origin.
+
+SET MOUSE THRESHOLD
+-------------------
+
+::
+
+    0x0B
+    X                   ; x threshold in mouse ticks (positive integers)
+    Y                   ; y threshold in mouse ticks (positive integers)
+
+This command sets the threshold before a mouse event is generated. Note that
+it does NOT affect the resolution of the data returned to the host. This
+command is valid only in RELATIVE MOUSE POSITIONING mode. The thresholds
+default to 1 at RESET (or power-up).
+
+SET MOUSE SCALE
+---------------
+
+::
+
+    0x0C
+    X                   ; horizontal mouse ticks per internal X
+    Y                   ; vertical mouse ticks per internal Y
+
+This command sets the scale factor for the ABSOLUTE MOUSE POSITIONING mode.
+In this mode, the specified number of mouse phase changes ('clicks') must
+occur before the internally maintained coordinate is changed by one
+(independently scaled for each axis). Remember that the mouse position
+information is available only by interrogating the ikbd in the ABSOLUTE MOUSE
+POSITIONING mode unless the ikbd has been commanded to report on button press
+or release (see SET MOSE BUTTON ACTION).
+
+INTERROGATE MOUSE POSITION
+--------------------------
+
+::
+
+    0x0D
+    Returns:
+            0xF7       ; absolute mouse position header
+    BUTTONS
+            0000dcba   ; where a is right button down since last interrogation
+                       ; b is right button up since last
+                       ; c is left button down since last
+                       ; d is left button up since last
+            XMSB       ; X coordinate
+            XLSB
+            YMSB       ; Y coordinate
+            YLSB
+
+The INTERROGATE MOUSE POSITION command is valid when in the ABSOLUTE MOUSE
+POSITIONING mode, regardless of the setting of the MOUSE BUTTON ACTION.
+
+LOAD MOUSE POSITION
+-------------------
+
+::
+
+    0x0E
+    0x00                ; filler
+    XMSB                ; X coordinate
+    XLSB                ; (in scaled coordinate system)
+    YMSB                ; Y coordinate
+    YLSB
+
+This command allows the user to preset the internally maintained absolute
+mouse position.
+
+SET Y=0 AT BOTTOM
+-----------------
+
+::
+
+    0x0F
+
+This command makes the origin of the Y axis to be at the bottom of the
+logical coordinate system internal to the ikbd for all relative or absolute
+mouse motion. This causes mouse motion toward the user to be negative in sign
+and away from the user to be positive.
+
+SET Y=0 AT TOP
+--------------
+
+::
+
+    0x10
+
+Makes the origin of the Y axis to be at the top of the logical coordinate
+system within the ikbd for all relative or absolute mouse motion. (DEFAULT)
+This causes mouse motion toward the user to be positive in sign and away from
+the user to be negative.
+
+RESUME
+------
+
+::
+
+    0x11
+
+Resume sending data to the host. Since any command received by the ikbd after
+its output has been paused also causes an implicit RESUME this command can be
+thought of as a NO OPERATION command. If this command is received by the ikbd
+and it is not PAUSED, it is simply ignored.
+
+DISABLE MOUSE
+-------------
+
+::
+
+    0x12
+
+All mouse event reporting is disabled (and scanning may be internally
+disabled). Any valid mouse mode command resumes mouse motion monitoring. (The
+valid mouse mode commands are SET RELATIVE MOUSE POSITION REPORTING, SET
+ABSOLUTE MOUSE POSITIONING, and SET MOUSE KEYCODE MODE. )
+N.B. If the mouse buttons have been commanded to act like keyboard keys, this
+command DOES affect their actions.
+
+PAUSE OUTPUT
+------------
+
+::
+
+    0x13
+
+Stop sending data to the host until another valid command is received. Key
+matrix activity is still monitored and scan codes or ASCII characters enqueued
+(up to the maximum supported by the microcontroller) to be sent when the host
+allows the output to be resumed. If in the JOYSTICK EVENT REPORTING mode,
+joystick events are also queued.
+Mouse motion should be accumulated while the output is paused. If the ikbd is
+in RELATIVE MOUSE POSITIONING REPORTING mode, motion is accumulated beyond the
+normal threshold limits to produce the minimum number of packets necessary for
+transmission when output is resumed. Pressing or releasing either mouse button
+causes any accumulated motion to be immediately queued as packets, if the
+mouse is in RELATIVE MOUSE POSITION REPORTING mode.
+Because of the limitations of the microcontroller memory this command should
+be used sparingly, and the output should not be shut of for more than <tbd>
+milliseconds at a time.
+The output is stopped only at the end of the current 'even'. If the PAUSE
+OUTPUT command is received in the middle of a multiple byte report, the packet
+will still be transmitted to conclusion and then the PAUSE will take effect.
+When the ikbd is in either the JOYSTICK MONITORING mode or the FIRE BUTTON
+MONITORING mode, the PAUSE OUTPUT command also temporarily stops the
+monitoring process (i.e. the samples are not enqueued for transmission).
+
+SET JOYSTICK EVENT REPORTING
+----------------------------
+
+::
+
+    0x14
+
+Enter JOYSTICK EVENT REPORTING mode (DEFAULT). Each opening or closure of a
+joystick switch or trigger causes a joystick event record to be generated.
+
+SET JOYSTICK INTERROGATION MODE
+-------------------------------
+
+::
+
+    0x15
+
+Disables JOYSTICK EVENT REPORTING. Host must send individual JOYSTICK
+INTERROGATE commands to sense joystick state.
+
+JOYSTICK INTERROGATE
+--------------------
+
+::
+
+    0x16
+
+Return a record indicating the current state of the joysticks. This command
+is valid in either the JOYSTICK EVENT REPORTING mode or the JOYSTICK
+INTERROGATION MODE.
+
+SET JOYSTICK MONITORING
+-----------------------
+
+::
+
+    0x17
+    rate                ; time between samples in hundredths of a second
+    Returns: (in packets of two as long as in mode)
+            %000000xy   ; where y is JOYSTICK1 Fire button
+                        ; and x is JOYSTICK0 Fire button
+            %nnnnmmmm   ; where m is JOYSTICK1 state
+                        ; and n is JOYSTICK0 state
+
+Sets the ikbd to do nothing but monitor the serial command line, maintain the
+time-of-day clock, and monitor the joystick. The rate sets the interval
+between joystick samples.
+N.B. The user should not set the rate higher than the serial communications
+channel will allow the 2 bytes packets to be transmitted.
+
+SET FIRE BUTTON MONITORING
+--------------------------
+
+::
+
+    0x18
+    Returns: (as long as in mode)
+            %bbbbbbbb   ; state of the JOYSTICK1 fire button packed
+                        ; 8 bits per byte, the first sample if the MSB
+
+Set the ikbd to do nothing but monitor the serial command line, maintain the
+time-of-day clock, and monitor the fire button on Joystick 1. The fire button
+is scanned at a rate that causes 8 samples to be made in the time it takes for
+the previous byte to be sent to the host (i.e. scan rate = 8/10 * baud rate).
+The sample interval should be as constant as possible.
+
+SET JOYSTICK KEYCODE MODE
+-------------------------
+
+::
+
+    0x19
+    RX                  ; length of time (in tenths of seconds) until
+                        ; horizontal velocity breakpoint is reached
+    RY                  ; length of time (in tenths of seconds) until
+                        ; vertical velocity breakpoint is reached
+    TX                  ; length (in tenths of seconds) of joystick closure
+                        ; until horizontal cursor key is generated before RX
+                        ; has elapsed
+    TY                  ; length (in tenths of seconds) of joystick closure
+                        ; until vertical cursor key is generated before RY
+                        ; has elapsed
+    VX                  ; length (in tenths of seconds) of joystick closure
+                        ; until horizontal cursor keystrokes are generated
+                        ; after RX has elapsed
+    VY                  ; length (in tenths of seconds) of joystick closure
+                        ; until vertical cursor keystrokes are generated
+                        ; after RY has elapsed
+
+In this mode, joystick 0 is scanned in a way that simulates cursor keystrokes.
+On initial closure, a keystroke pair (make/break) is generated. Then up to Rn
+tenths of seconds later, keystroke pairs are generated every Tn tenths of
+seconds. After the Rn breakpoint is reached, keystroke pairs are generated
+every Vn tenths of seconds. This provides a velocity (auto-repeat) breakpoint
+feature.
+Note that by setting RX and/or Ry to zero, the velocity feature can be
+disabled. The values of TX and TY then become meaningless, and the generation
+of cursor 'keystrokes' is set by VX and VY.
+
+DISABLE JOYSTICKS
+-----------------
+
+::
+
+    0x1A
+
+Disable the generation of any joystick events (and scanning may be internally
+disabled). Any valid joystick mode command resumes joystick monitoring. (The
+joystick mode commands are SET JOYSTICK EVENT REPORTING, SET JOYSTICK
+INTERROGATION MODE, SET JOYSTICK MONITORING, SET FIRE BUTTON MONITORING, and
+SET JOYSTICK KEYCODE MODE.)
+
+TIME-OF-DAY CLOCK SET
+---------------------
+
+::
+
+    0x1B
+    YY                  ; year (2 least significant digits)
+    MM                  ; month
+    DD                  ; day
+    hh                  ; hour
+    mm                  ; minute
+    ss                  ; second
+
+All time-of-day data should be sent to the ikbd in packed BCD format.
+Any digit that is not a valid BCD digit should be treated as a 'don't care'
+and not alter that particular field of the date or time. This permits setting
+only some subfields of the time-of-day clock.
+
+INTERROGATE TIME-OF-DAT CLOCK
+-----------------------------
+
+::
+
+    0x1C
+    Returns:
+            0xFC        ; time-of-day event header
+            YY          ; year (2 least significant digits)
+            MM          ; month
+            DD          ; day
+            hh          ; hour
+            mm          ; minute
+            ss          ; second
+
+    All time-of-day is sent in packed BCD format.
+
+MEMORY LOAD
+-----------
+
+::
+
+    0x20
+    ADRMSB              ; address in controller
+    ADRLSB              ; memory to be loaded
+    NUM                 ; number of bytes (0-128)
+    { data }
+
+This command permits the host to load arbitrary values into the ikbd
+controller memory. The time between data bytes must be less than 20ms.
+
+MEMORY READ
+-----------
+
+::
+
+    0x21
+    ADRMSB              ; address in controller
+    ADRLSB              ; memory to be read
+    Returns:
+            0xF6        ; status header
+            0x20        ; memory access
+            { data }    ; 6 data bytes starting at ADR
+
+This command permits the host to read from the ikbd controller memory.
+
+CONTROLLER EXECUTE
+------------------
+
+::
+
+    0x22
+    ADRMSB              ; address of subroutine in
+    ADRLSB              ; controller memory to be called
+
+This command allows the host to command the execution of a subroutine in the
+ikbd controller memory.
+
+STATUS INQUIRIES
+----------------
+
+::
+
+    Status commands are formed by inclusively ORing 0x80 with the
+    relevant SET command.
+
+    Example:
+    0x88 (or 0x89 or 0x8A)  ; request mouse mode
+    Returns:
+            0xF6        ; status response header
+            mode        ; 0x08 is RELATIVE
+                        ; 0x09 is ABSOLUTE
+                        ; 0x0A is KEYCODE
+            param1      ; 0 is RELATIVE
+                        ; XMSB maximum if ABSOLUTE
+                        ; DELTA X is KEYCODE
+            param2      ; 0 is RELATIVE
+                        ; YMSB maximum if ABSOLUTE
+                        ; DELTA Y is KEYCODE
+            param3      ; 0 if RELATIVE
+                        ; or KEYCODE
+                        ; YMSB is ABSOLUTE
+            param4      ; 0 if RELATIVE
+                        ; or KEYCODE
+                        ; YLSB is ABSOLUTE
+            0           ; pad
+            0
+
+The STATUS INQUIRY commands request the ikbd to return either the current mode
+or the parameters associated with a given command. All status reports are
+padded to form 8 byte long return packets. The responses to the status
+requests are designed so that the host may store them away (after stripping
+off the status report header byte) and later send them back as commands to
+ikbd to restore its state. The 0 pad bytes will be treated as NOPs by the
+ikbd.
+
+    Valid STATUS INQUIRY commands are::
+
+            0x87    mouse button action
+            0x88    mouse mode
+            0x89
+            0x8A
+            0x8B    mnouse threshold
+            0x8C    mouse scale
+            0x8F    mouse vertical coordinates
+            0x90    ( returns       0x0F Y=0 at bottom
+                            0x10 Y=0 at top )
+            0x92    mouse enable/disable
+                    ( returns       0x00 enabled)
+                            0x12 disabled )
+            0x94    joystick mode
+            0x95
+            0x96
+            0x9A    joystick enable/disable
+                    ( returns       0x00 enabled
+                            0x1A disabled )
+
+It is the (host) programmer's responsibility to have only one unanswered
+inquiry in process at a time.
+STATUS INQUIRY commands are not valid if the ikbd is in JOYSTICK MONITORING
+mode or FIRE BUTTON MONITORING mode.
+
+
+SCAN CODES
+==========
+
+The key scan codes returned by the ikbd are chosen to simplify the
+implementation of GSX.
+
+GSX Standard Keyboard Mapping
+
+======= ============
+Hex    Keytop
+======= ============
+01     Esc
+02     1
+03     2
+04     3
+05     4
+06     5
+07     6
+08     7
+09     8
+0A     9
+0B     0
+0C     \-
+0D     \=
+0E     BS
+0F     TAB
+10     Q
+11     W
+12     E
+13     R
+14     T
+15     Y
+16     U
+17     I
+18     O
+19     P
+1A     [
+1B     ]
+1C     RET
+1D     CTRL
+1E     A
+1F     S
+20     D
+21     F
+22     G
+23     H
+24     J
+25     K
+26     L
+27     ;
+28     '
+29     \`
+2A     (LEFT) SHIFT
+2B     \\
+2C     Z
+2D     X
+2E     C
+2F     V
+30     B
+31     N
+32     M
+33     ,
+34     .
+35     /
+36     (RIGHT) SHIFT
+37     { NOT USED }
+38     ALT
+39     SPACE BAR
+3A     CAPS LOCK
+3B     F1
+3C     F2
+3D     F3
+3E     F4
+3F     F5
+40     F6
+41     F7
+42     F8
+43     F9
+44     F10
+45     { NOT USED }
+46     { NOT USED }
+47     HOME
+48     UP ARROW
+49     { NOT USED }
+4A     KEYPAD -
+4B     LEFT ARROW
+4C     { NOT USED }
+4D     RIGHT ARROW
+4E     KEYPAD +
+4F     { NOT USED }
+50     DOWN ARROW
+51     { NOT USED }
+52     INSERT
+53     DEL
+54     { NOT USED }
+5F     { NOT USED }
+60     ISO KEY
+61     UNDO
+62     HELP
+63     KEYPAD (
+64     KEYPAD /
+65     KEYPAD *
+66     KEYPAD *
+67     KEYPAD 7
+68     KEYPAD 8
+69     KEYPAD 9
+6A     KEYPAD 4
+6B     KEYPAD 5
+6C     KEYPAD 6
+6D     KEYPAD 1
+6E     KEYPAD 2
+6F     KEYPAD 3
+70     KEYPAD 0
+71     KEYPAD .
+72     KEYPAD ENTER
+======= ============
diff --git a/Documentation/input/devices/bcm5974.rst b/Documentation/input/devices/bcm5974.rst
new file mode 100644 (file)
index 0000000..4aca199
--- /dev/null
@@ -0,0 +1,70 @@
+.. include:: <isonum.txt>
+
+------------------------
+BCM5974 Driver (bcm5974)
+------------------------
+
+:Copyright: |copy| 2008-2009   Henrik Rydberg <rydberg@euromail.se>
+
+The USB initialization and package decoding was made by Scott Shawcroft as
+part of the touchd user-space driver project:
+
+:Copyright: |copy| 2008        Scott Shawcroft (scott.shawcroft@gmail.com)
+
+The BCM5974 driver is based on the appletouch driver:
+
+:Copyright: |copy| 2001-2004   Greg Kroah-Hartman (greg@kroah.com)
+:Copyright: |copy| 2005                Johannes Berg (johannes@sipsolutions.net)
+:Copyright: |copy| 2005                Stelian Pop (stelian@popies.net)
+:Copyright: |copy| 2005                Frank Arnold (frank@scirocco-5v-turbo.de)
+:Copyright: |copy| 2005                Peter Osterlund (petero2@telia.com)
+:Copyright: |copy| 2005                Michael Hanselmann (linux-kernel@hansmi.ch)
+:Copyright: |copy| 2006                Nicolas Boichat (nicolas@boichat.ch)
+
+This driver adds support for the multi-touch trackpad on the new Apple
+Macbook Air and Macbook Pro laptops. It replaces the appletouch driver on
+those computers, and integrates well with the synaptics driver of the Xorg
+system.
+
+Known to work on Macbook Air, Macbook Pro Penryn and the new unibody
+Macbook 5 and Macbook Pro 5.
+
+Usage
+-----
+
+The driver loads automatically for the supported usb device ids, and
+becomes available both as an event device (/dev/input/event*) and as a
+mouse via the mousedev driver (/dev/input/mice).
+
+USB Race
+--------
+
+The Apple multi-touch trackpads report both mouse and keyboard events via
+different interfaces of the same usb device. This creates a race condition
+with the HID driver, which, if not told otherwise, will find the standard
+HID mouse and keyboard, and claim the whole device. To remedy, the usb
+product id must be listed in the mouse_ignore list of the hid driver.
+
+Debug output
+------------
+
+To ease the development for new hardware version, verbose packet output can
+be switched on with the debug kernel module parameter. The range [1-9]
+yields different levels of verbosity. Example (as root)::
+
+    echo -n 9 > /sys/module/bcm5974/parameters/debug
+
+    tail -f /var/log/debug
+
+    echo -n 0 > /sys/module/bcm5974/parameters/debug
+
+Trivia
+------
+
+The driver was developed at the ubuntu forums in June 2008 [#f1]_, and now has
+a more permanent home at bitmath.org [#f2]_.
+
+.. Links
+
+.. [#f1] http://ubuntuforums.org/showthread.php?t=840040
+.. [#f2] http://bitmath.org/code/
diff --git a/Documentation/input/devices/cma3000_d0x.rst b/Documentation/input/devices/cma3000_d0x.rst
new file mode 100644 (file)
index 0000000..8bc8e61
--- /dev/null
@@ -0,0 +1,139 @@
+CMA3000-D0x Accelerometer
+=========================
+
+Supported chips:
+* VTI CMA3000-D0x
+
+Datasheet:
+  CMA3000-D0X Product Family Specification 8281000A.02.pdf
+  <http://www.vti.fi/en/>
+
+:Author: Hemanth V <hemanthv@ti.com>
+
+
+Description
+-----------
+
+CMA3000 Tri-axis accelerometer supports Motion detect, Measurement and
+Free fall modes.
+
+Motion Detect Mode:
+    Its the low power mode where interrupts are generated only
+    when motion exceeds the defined thresholds.
+
+Measurement Mode:
+    This mode is used to read the acceleration data on X,Y,Z
+    axis and supports 400, 100, 40 Hz sample frequency.
+
+Free fall Mode:
+    This mode is intended to save system resources.
+
+Threshold values:
+    Chip supports defining threshold values for above modes
+    which includes time and g value. Refer product specifications for
+    more details.
+
+CMA3000 chip supports mutually exclusive I2C and SPI interfaces for
+communication, currently the driver supports I2C based communication only.
+Initial configuration for bus mode is set in non volatile memory and can later
+be modified through bus interface command.
+
+Driver reports acceleration data through input subsystem. It generates ABS_MISC
+event with value 1 when free fall is detected.
+
+Platform data need to be configured for initial default values.
+
+Platform Data
+-------------
+
+fuzz_x:
+    Noise on X Axis
+
+fuzz_y:
+    Noise on Y Axis
+
+fuzz_z:
+    Noise on Z Axis
+
+g_range:
+    G range in milli g i.e 2000 or 8000
+
+mode:
+    Default Operating mode
+
+mdthr:
+    Motion detect g range threshold value
+
+mdfftmr:
+    Motion detect and free fall time threshold value
+
+ffthr:
+    Free fall g range threshold value
+
+Input Interface
+---------------
+
+Input driver version is 1.0.0
+Input device ID: bus 0x18 vendor 0x0 product 0x0 version 0x0
+Input device name: "cma3000-accelerometer"
+
+Supported events::
+
+  Event type 0 (Sync)
+  Event type 3 (Absolute)
+    Event code 0 (X)
+      Value     47
+      Min    -8000
+      Max     8000
+      Fuzz     200
+    Event code 1 (Y)
+      Value    -28
+      Min    -8000
+      Max     8000
+      Fuzz     200
+    Event code 2 (Z)
+      Value    905
+      Min    -8000
+      Max     8000
+      Fuzz     200
+    Event code 40 (Misc)
+      Value      0
+      Min        0
+      Max        1
+  Event type 4 (Misc)
+
+
+Register/Platform parameters Description
+----------------------------------------
+
+mode::
+
+       0: power down mode
+       1: 100 Hz Measurement mode
+       2: 400 Hz Measurement mode
+       3: 40 Hz Measurement mode
+       4: Motion Detect mode (default)
+       5: 100 Hz Free fall mode
+       6: 40 Hz Free fall mode
+       7: Power off mode
+
+grange::
+
+       2000: 2000 mg or 2G Range
+       8000: 8000 mg or 8G Range
+
+mdthr::
+
+       X: X * 71mg (8G Range)
+       X: X * 18mg (2G Range)
+
+mdfftmr::
+
+       X: (X & 0x70) * 100 ms (MDTMR)
+          (X & 0x0F) * 2.5 ms (FFTMR 400 Hz)
+          (X & 0x0F) * 10 ms  (FFTMR 100 Hz)
+
+ffthr::
+
+       X: (X >> 2) * 18mg (2G Range)
+       X: (X & 0x0F) * 71 mg (8G Range)
diff --git a/Documentation/input/devices/cs461x.rst b/Documentation/input/devices/cs461x.rst
new file mode 100644 (file)
index 0000000..b1e6d50
--- /dev/null
@@ -0,0 +1,43 @@
+Crystal SoundFusion CS4610/CS4612/CS461 joystick
+================================================
+
+This is a new low-level driver to support analog joystick attached to
+Crystal SoundFusion CS4610/CS4612/CS4615. This code is based upon
+Vortex/Solo drivers as an example of decoration style, and ALSA
+0.5.8a kernel drivers as an chipset documentation and samples.
+
+This version does not have cooked mode support; the basic code
+is present here, but have not tested completely. The button analysis
+is completed in this mode, but the axis movement is not.
+
+Raw mode works fine with analog joystick front-end driver and cs461x
+driver as a backend. I've tested this driver with CS4610, 4-axis and
+4-button joystick; I mean the jstest utility. Also I've tried to
+play in xracer game using joystick, and the result is better than
+keyboard only mode.
+
+The sensitivity and calibrate quality have not been tested; the two
+reasons are performed: the same hardware cannot work under Win95 (blue
+screen in VJOYD); I have no documentation on my chip; and the existing
+behavior in my case was not raised the requirement of joystick calibration.
+So the driver have no code to perform hardware related calibration.
+
+This driver have the basic support for PCI devices only; there is no
+ISA or PnP ISA cards supported.
+
+The driver works with ALSA drivers simultaneously. For example, the xracer
+uses joystick as input device and PCM device as sound output in one time.
+There are no sound or input collisions detected. The source code have
+comments about them; but I've found the joystick can be initialized
+separately of ALSA modules. So, you can use only one joystick driver
+without ALSA drivers. The ALSA drivers are not needed to compile or
+run this driver.
+
+There are no debug information print have been placed in source, and no
+specific options required to work this driver. The found chipset parameters
+are printed via printk(KERN_INFO "..."), see the /var/log/messages to
+inspect cs461x: prefixed messages to determine possible card detection
+errors.
+
+Regards,
+Viktor
diff --git a/Documentation/input/devices/edt-ft5x06.rst b/Documentation/input/devices/edt-ft5x06.rst
new file mode 100644 (file)
index 0000000..2032f0b
--- /dev/null
@@ -0,0 +1,54 @@
+EDT ft5x06 based Polytouch devices
+----------------------------------
+
+The edt-ft5x06 driver is useful for the EDT "Polytouch" family of capacitive
+touch screens. Note that it is *not* suitable for other devices based on the
+focaltec ft5x06 devices, since they contain vendor-specific firmware. In
+particular this driver is not suitable for the Nook tablet.
+
+It has been tested with the following devices:
+  * EP0350M06
+  * EP0430M06
+  * EP0570M06
+  * EP0700M06
+
+The driver allows configuration of the touch screen via a set of sysfs files:
+
+/sys/class/input/eventX/device/device/threshold:
+    allows setting the "click"-threshold in the range from 20 to 80.
+
+/sys/class/input/eventX/device/device/gain:
+    allows setting the sensitivity in the range from 0 to 31. Note that
+    lower values indicate higher sensitivity.
+
+/sys/class/input/eventX/device/device/offset:
+    allows setting the edge compensation in the range from 0 to 31.
+
+/sys/class/input/eventX/device/device/report_rate:
+    allows setting the report rate in the range from 3 to 14.
+
+
+For debugging purposes the driver provides a few files in the debug
+filesystem (if available in the kernel). In /sys/kernel/debug/edt_ft5x06
+you'll find the following files:
+
+num_x, num_y:
+    (readonly) contains the number of sensor fields in X- and
+    Y-direction.
+
+mode:
+    allows switching the sensor between "factory mode" and "operation
+    mode" by writing "1" or "0" to it. In factory mode (1) it is
+    possible to get the raw data from the sensor. Note that in factory
+    mode regular events don't get delivered and the options described
+    above are unavailable.
+
+raw_data:
+    contains num_x * num_y big endian 16 bit values describing the raw
+    values for each sensor field. Note that each read() call on this
+    files triggers a new readout. It is recommended to provide a buffer
+    big enough to contain num_x * num_y * 2 bytes.
+
+Note that reading raw_data gives a I/O error when the device is not in factory
+mode. The same happens when reading/writing to the parameter files when the
+device is not in regular operation mode.
diff --git a/Documentation/input/devices/elantech.rst b/Documentation/input/devices/elantech.rst
new file mode 100644 (file)
index 0000000..c3374a7
--- /dev/null
@@ -0,0 +1,841 @@
+Elantech Touchpad Driver
+========================
+
+       Copyright (C) 2007-2008 Arjan Opmeer <arjan@opmeer.net>
+
+       Extra information for hardware version 1 found and
+       provided by Steve Havelka
+
+       Version 2 (EeePC) hardware support based on patches
+       received from Woody at Xandros and forwarded to me
+       by user StewieGriffin at the eeeuser.com forum
+
+.. Contents
+
+ 1. Introduction
+ 2. Extra knobs
+ 3. Differentiating hardware versions
+ 4. Hardware version 1
+    4.1 Registers
+    4.2 Native relative mode 4 byte packet format
+    4.3 Native absolute mode 4 byte packet format
+ 5. Hardware version 2
+    5.1 Registers
+    5.2 Native absolute mode 6 byte packet format
+        5.2.1 Parity checking and packet re-synchronization
+        5.2.2 One/Three finger touch
+        5.2.3 Two finger touch
+ 6. Hardware version 3
+    6.1 Registers
+    6.2 Native absolute mode 6 byte packet format
+        6.2.1 One/Three finger touch
+        6.2.2 Two finger touch
+ 7. Hardware version 4
+    7.1 Registers
+    7.2 Native absolute mode 6 byte packet format
+        7.2.1 Status packet
+        7.2.2 Head packet
+        7.2.3 Motion packet
+ 8. Trackpoint (for Hardware version 3 and 4)
+    8.1 Registers
+    8.2 Native relative mode 6 byte packet format
+        8.2.1 Status Packet
+
+
+
+Introduction
+~~~~~~~~~~~~
+
+Currently the Linux Elantech touchpad driver is aware of four different
+hardware versions unimaginatively called version 1,version 2, version 3
+and version 4. Version 1 is found in "older" laptops and uses 4 bytes per
+packet. Version 2 seems to be introduced with the EeePC and uses 6 bytes
+per packet, and provides additional features such as position of two fingers,
+and width of the touch.  Hardware version 3 uses 6 bytes per packet (and
+for 2 fingers the concatenation of two 6 bytes packets) and allows tracking
+of up to 3 fingers. Hardware version 4 uses 6 bytes per packet, and can
+combine a status packet with multiple head or motion packets. Hardware version
+4 allows tracking up to 5 fingers.
+
+Some Hardware version 3 and version 4 also have a trackpoint which uses a
+separate packet format. It is also 6 bytes per packet.
+
+The driver tries to support both hardware versions and should be compatible
+with the Xorg Synaptics touchpad driver and its graphical configuration
+utilities.
+
+Note that a mouse button is also associated with either the touchpad or the
+trackpoint when a trackpoint is available.  Disabling the Touchpad in xorg
+(TouchPadOff=0) will also disable the buttons associated with the touchpad.
+
+Additionally the operation of the touchpad can be altered by adjusting the
+contents of some of its internal registers. These registers are represented
+by the driver as sysfs entries under /sys/bus/serio/drivers/psmouse/serio?
+that can be read from and written to.
+
+Currently only the registers for hardware version 1 are somewhat understood.
+Hardware version 2 seems to use some of the same registers but it is not
+known whether the bits in the registers represent the same thing or might
+have changed their meaning.
+
+On top of that, some register settings have effect only when the touchpad is
+in relative mode and not in absolute mode. As the Linux Elantech touchpad
+driver always puts the hardware into absolute mode not all information
+mentioned below can be used immediately. But because there is no freely
+available Elantech documentation the information is provided here anyway for
+completeness sake.
+
+
+Extra knobs
+~~~~~~~~~~~
+
+Currently the Linux Elantech touchpad driver provides three extra knobs under
+/sys/bus/serio/drivers/psmouse/serio? for the user.
+
+* debug
+
+   Turn different levels of debugging ON or OFF.
+
+   By echoing "0" to this file all debugging will be turned OFF.
+
+   Currently a value of "1" will turn on some basic debugging and a value of
+   "2" will turn on packet debugging. For hardware version 1 the default is
+   OFF. For version 2 the default is "1".
+
+   Turning packet debugging on will make the driver dump every packet
+   received to the syslog before processing it. Be warned that this can
+   generate quite a lot of data!
+
+* paritycheck
+
+   Turns parity checking ON or OFF.
+
+   By echoing "0" to this file parity checking will be turned OFF. Any
+   non-zero value will turn it ON. For hardware version 1 the default is ON.
+   For version 2 the default it is OFF.
+
+   Hardware version 1 provides basic data integrity verification by
+   calculating a parity bit for the last 3 bytes of each packet. The driver
+   can check these bits and reject any packet that appears corrupted. Using
+   this knob you can bypass that check.
+
+   Hardware version 2 does not provide the same parity bits. Only some basic
+   data consistency checking can be done. For now checking is disabled by
+   default. Currently even turning it on will do nothing.
+
+* crc_enabled
+
+   Sets crc_enabled to 0/1. The name "crc_enabled" is the official name of
+   this integrity check, even though it is not an actual cyclic redundancy
+   check.
+
+   Depending on the state of crc_enabled, certain basic data integrity
+   verification is done by the driver on hardware version 3 and 4. The
+   driver will reject any packet that appears corrupted. Using this knob,
+   The state of crc_enabled can be altered with this knob.
+
+   Reading the crc_enabled value will show the active value. Echoing
+   "0" or "1" to this file will set the state to "0" or "1".
+
+Differentiating hardware versions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To detect the hardware version, read the version number as param[0].param[1].param[2]::
+
+ 4 bytes version: (after the arrow is the name given in the Dell-provided driver)
+ 02.00.22 => EF013
+ 02.06.00 => EF019
+
+In the wild, there appear to be more versions, such as 00.01.64, 01.00.21,
+02.00.00, 02.00.04, 02.00.06::
+
+ 6 bytes:
+ 02.00.30 => EF113
+ 02.08.00 => EF023
+ 02.08.XX => EF123
+ 02.0B.00 => EF215
+ 04.01.XX => Scroll_EF051
+ 04.02.XX => EF051
+
+In the wild, there appear to be more versions, such as 04.03.01, 04.04.11. There
+appears to be almost no difference, except for EF113, which does not report
+pressure/width and has different data consistency checks.
+
+Probably all the versions with param[0] <= 01 can be considered as
+4 bytes/firmware 1. The versions < 02.08.00, with the exception of 02.00.30, as
+4 bytes/firmware 2. Everything >= 02.08.00 can be considered as 6 bytes.
+
+
+Hardware version 1
+~~~~~~~~~~~~~~~~~~
+
+Registers
+---------
+
+By echoing a hexadecimal value to a register it contents can be altered.
+
+For example::
+
+   echo -n 0x16 > reg_10
+
+* reg_10::
+
+   bit   7   6   5   4   3   2   1   0
+         B   C   T   D   L   A   S   E
+
+         E: 1 = enable smart edges unconditionally
+         S: 1 = enable smart edges only when dragging
+         A: 1 = absolute mode (needs 4 byte packets, see reg_11)
+         L: 1 = enable drag lock (see reg_22)
+         D: 1 = disable dynamic resolution
+         T: 1 = disable tapping
+         C: 1 = enable corner tap
+         B: 1 = swap left and right button
+
+* reg_11::
+
+   bit   7   6   5   4   3   2   1   0
+         1   0   0   H   V   1   F   P
+
+         P: 1 = enable parity checking for relative mode
+         F: 1 = enable native 4 byte packet mode
+         V: 1 = enable vertical scroll area
+         H: 1 = enable horizontal scroll area
+
+* reg_20::
+
+         single finger width?
+
+* reg_21::
+
+         scroll area width (small: 0x40 ... wide: 0xff)
+
+* reg_22::
+
+         drag lock time out (short: 0x14 ... long: 0xfe;
+                             0xff = tap again to release)
+
+* reg_23::
+
+         tap make timeout?
+
+* reg_24::
+
+         tap release timeout?
+
+* reg_25::
+
+         smart edge cursor speed (0x02 = slow, 0x03 = medium, 0x04 = fast)
+
+* reg_26::
+
+         smart edge activation area width?
+
+
+Native relative mode 4 byte packet format
+-----------------------------------------
+
+byte 0::
+
+   bit   7   6   5   4   3   2   1   0
+         c   c  p2  p1   1   M   R   L
+
+         L, R, M = 1 when Left, Right, Middle mouse button pressed
+            some models have M as byte 3 odd parity bit
+         when parity checking is enabled (reg_11, P = 1):
+            p1..p2 = byte 1 and 2 odd parity bit
+         c = 1 when corner tap detected
+
+byte 1::
+
+   bit   7   6   5   4   3   2   1   0
+        dx7 dx6 dx5 dx4 dx3 dx2 dx1 dx0
+
+         dx7..dx0 = x movement;   positive = right, negative = left
+         byte 1 = 0xf0 when corner tap detected
+
+byte 2::
+
+   bit   7   6   5   4   3   2   1   0
+        dy7 dy6 dy5 dy4 dy3 dy2 dy1 dy0
+
+         dy7..dy0 = y movement;   positive = up,    negative = down
+
+byte 3::
+
+   parity checking enabled (reg_11, P = 1):
+
+      bit   7   6   5   4   3   2   1   0
+            w   h  n1  n0  ds3 ds2 ds1 ds0
+
+            normally:
+               ds3..ds0 = scroll wheel amount and direction
+                          positive = down or left
+                          negative = up or right
+            when corner tap detected:
+               ds0 = 1 when top right corner tapped
+               ds1 = 1 when bottom right corner tapped
+               ds2 = 1 when bottom left corner tapped
+               ds3 = 1 when top left corner tapped
+            n1..n0 = number of fingers on touchpad
+               only models with firmware 2.x report this, models with
+               firmware 1.x seem to map one, two and three finger taps
+               directly to L, M and R mouse buttons
+            h = 1 when horizontal scroll action
+            w = 1 when wide finger touch?
+
+   otherwise (reg_11, P = 0):
+
+      bit   7   6   5   4   3   2   1   0
+           ds7 ds6 ds5 ds4 ds3 ds2 ds1 ds0
+
+            ds7..ds0 = vertical scroll amount and direction
+                       negative = up
+                       positive = down
+
+
+Native absolute mode 4 byte packet format
+-----------------------------------------
+
+EF013 and EF019 have a special behaviour (due to a bug in the firmware?), and
+when 1 finger is touching, the first 2 position reports must be discarded.
+This counting is reset whenever a different number of fingers is reported.
+
+byte 0::
+
+   firmware version 1.x:
+
+      bit   7   6   5   4   3   2   1   0
+            D   U  p1  p2   1  p3   R   L
+
+            L, R = 1 when Left, Right mouse button pressed
+            p1..p3 = byte 1..3 odd parity bit
+            D, U = 1 when rocker switch pressed Up, Down
+
+   firmware version 2.x:
+
+      bit   7   6   5   4   3   2   1   0
+           n1  n0  p2  p1   1  p3   R   L
+
+            L, R = 1 when Left, Right mouse button pressed
+            p1..p3 = byte 1..3 odd parity bit
+            n1..n0 = number of fingers on touchpad
+
+byte 1::
+
+   firmware version 1.x:
+
+      bit   7   6   5   4   3   2   1   0
+            f   0  th  tw  x9  x8  y9  y8
+
+            tw = 1 when two finger touch
+            th = 1 when three finger touch
+            f  = 1 when finger touch
+
+   firmware version 2.x:
+
+      bit   7   6   5   4   3   2   1   0
+            .   .   .   .  x9  x8  y9  y8
+
+byte 2::
+
+   bit   7   6   5   4   3   2   1   0
+        x7  x6  x5  x4  x3  x2  x1  x0
+
+         x9..x0 = absolute x value (horizontal)
+
+byte 3::
+
+   bit   7   6   5   4   3   2   1   0
+        y7  y6  y5  y4  y3  y2  y1  y0
+
+         y9..y0 = absolute y value (vertical)
+
+
+Hardware version 2
+~~~~~~~~~~~~~~~~~~
+
+
+Registers
+---------
+
+By echoing a hexadecimal value to a register it contents can be altered.
+
+For example::
+
+   echo -n 0x56 > reg_10
+
+* reg_10::
+
+   bit   7   6   5   4   3   2   1   0
+         0   1   0   1   0   1   D   0
+
+         D: 1 = enable drag and drop
+
+* reg_11::
+
+   bit   7   6   5   4   3   2   1   0
+         1   0   0   0   S   0   1   0
+
+         S: 1 = enable vertical scroll
+
+* reg_21::
+
+         unknown (0x00)
+
+* reg_22::
+
+         drag and drop release time out (short: 0x70 ... long 0x7e;
+                                   0x7f = never i.e. tap again to release)
+
+
+Native absolute mode 6 byte packet format
+-----------------------------------------
+
+Parity checking and packet re-synchronization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is no parity checking, however some consistency checks can be performed.
+
+For instance for EF113::
+
+        SA1= packet[0];
+        A1 = packet[1];
+        B1 = packet[2];
+        SB1= packet[3];
+        C1 = packet[4];
+        D1 = packet[5];
+        if( (((SA1 & 0x3C) != 0x3C) && ((SA1 & 0xC0) != 0x80)) || // check Byte 1
+            (((SA1 & 0x0C) != 0x0C) && ((SA1 & 0xC0) == 0x80)) || // check Byte 1 (one finger pressed)
+            (((SA1 & 0xC0) != 0x80) && (( A1 & 0xF0) != 0x00)) || // check Byte 2
+            (((SB1 & 0x3E) != 0x38) && ((SA1 & 0xC0) != 0x80)) || // check Byte 4
+            (((SB1 & 0x0E) != 0x08) && ((SA1 & 0xC0) == 0x80)) || // check Byte 4 (one finger pressed)
+            (((SA1 & 0xC0) != 0x80) && (( C1 & 0xF0) != 0x00))  ) // check Byte 5
+               // error detected
+
+For all the other ones, there are just a few constant bits::
+
+        if( ((packet[0] & 0x0C) != 0x04) ||
+            ((packet[3] & 0x0f) != 0x02) )
+               // error detected
+
+
+In case an error is detected, all the packets are shifted by one (and packet[0] is discarded).
+
+One/Three finger touch
+^^^^^^^^^^^^^^^^^^^^^^
+
+byte 0::
+
+   bit   7   6   5   4   3   2   1   0
+        n1  n0  w3  w2   .   .   R   L
+
+         L, R = 1 when Left, Right mouse button pressed
+         n1..n0 = number of fingers on touchpad
+
+byte 1::
+
+   bit   7   6   5   4   3   2   1   0
+        p7  p6  p5  p4 x11 x10 x9  x8
+
+byte 2::
+
+   bit   7   6   5   4   3   2   1   0
+        x7  x6  x5  x4  x3  x2  x1  x0
+
+         x11..x0 = absolute x value (horizontal)
+
+byte 3::
+
+   bit   7   6   5   4   3   2   1   0
+        n4  vf  w1  w0   .   .   .  b2
+
+        n4 = set if more than 3 fingers (only in 3 fingers mode)
+        vf = a kind of flag ? (only on EF123, 0 when finger is over one
+             of the buttons, 1 otherwise)
+        w3..w0 = width of the finger touch (not EF113)
+        b2 (on EF113 only, 0 otherwise), b2.R.L indicates one button pressed:
+               0 = none
+               1 = Left
+               2 = Right
+               3 = Middle (Left and Right)
+               4 = Forward
+               5 = Back
+               6 = Another one
+               7 = Another one
+
+byte 4::
+
+   bit   7   6   5   4   3   2   1   0
+        p3  p1  p2  p0  y11 y10 y9  y8
+
+        p7..p0 = pressure (not EF113)
+
+byte 5::
+
+   bit   7   6   5   4   3   2   1   0
+        y7  y6  y5  y4  y3  y2  y1  y0
+
+         y11..y0 = absolute y value (vertical)
+
+
+Two finger touch
+^^^^^^^^^^^^^^^^
+
+Note that the two pairs of coordinates are not exactly the coordinates of the
+two fingers, but only the pair of the lower-left and upper-right coordinates.
+So the actual fingers might be situated on the other diagonal of the square
+defined by these two points.
+
+byte 0::
+
+   bit   7   6   5   4   3   2   1   0
+        n1  n0  ay8 ax8  .   .   R   L
+
+         L, R = 1 when Left, Right mouse button pressed
+         n1..n0 = number of fingers on touchpad
+
+byte 1::
+
+   bit   7   6   5   4   3   2   1   0
+        ax7 ax6 ax5 ax4 ax3 ax2 ax1 ax0
+
+        ax8..ax0 = lower-left finger absolute x value
+
+byte 2::
+
+   bit   7   6   5   4   3   2   1   0
+        ay7 ay6 ay5 ay4 ay3 ay2 ay1 ay0
+
+        ay8..ay0 = lower-left finger absolute y value
+
+byte 3::
+
+   bit   7   6   5   4   3   2   1   0
+         .   .  by8 bx8  .   .   .   .
+
+byte 4::
+
+   bit   7   6   5   4   3   2   1   0
+        bx7 bx6 bx5 bx4 bx3 bx2 bx1 bx0
+
+         bx8..bx0 = upper-right finger absolute x value
+
+byte 5::
+
+   bit   7   6   5   4   3   2   1   0
+        by7 by8 by5 by4 by3 by2 by1 by0
+
+         by8..by0 = upper-right finger absolute y value
+
+Hardware version 3
+~~~~~~~~~~~~~~~~~~
+
+Registers
+---------
+
+* reg_10::
+
+   bit   7   6   5   4   3   2   1   0
+         0   0   0   0   R   F   T   A
+
+         A: 1 = enable absolute tracking
+         T: 1 = enable two finger mode auto correct
+         F: 1 = disable ABS Position Filter
+         R: 1 = enable real hardware resolution
+
+Native absolute mode 6 byte packet format
+-----------------------------------------
+
+1 and 3 finger touch shares the same 6-byte packet format, except that
+3 finger touch only reports the position of the center of all three fingers.
+
+Firmware would send 12 bytes of data for 2 finger touch.
+
+Note on debounce:
+In case the box has unstable power supply or other electricity issues, or
+when number of finger changes, F/W would send "debounce packet" to inform
+driver that the hardware is in debounce status.
+The debouce packet has the following signature::
+
+    byte 0: 0xc4
+    byte 1: 0xff
+    byte 2: 0xff
+    byte 3: 0x02
+    byte 4: 0xff
+    byte 5: 0xff
+
+When we encounter this kind of packet, we just ignore it.
+
+One/Three finger touch
+^^^^^^^^^^^^^^^^^^^^^^
+
+byte 0::
+
+   bit   7   6   5   4   3   2   1   0
+        n1  n0  w3  w2   0   1   R   L
+
+        L, R = 1 when Left, Right mouse button pressed
+        n1..n0 = number of fingers on touchpad
+
+byte 1::
+
+   bit   7   6   5   4   3   2   1   0
+        p7  p6  p5  p4 x11 x10  x9  x8
+
+byte 2::
+
+   bit   7   6   5   4   3   2   1   0
+        x7  x6  x5  x4  x3  x2  x1  x0
+
+        x11..x0 = absolute x value (horizontal)
+
+byte 3::
+
+   bit   7   6   5   4   3   2   1   0
+         0   0  w1  w0   0   0   1   0
+
+         w3..w0 = width of the finger touch
+
+byte 4::
+
+   bit   7   6   5   4   3   2   1   0
+        p3  p1  p2  p0  y11 y10 y9  y8
+
+        p7..p0 = pressure
+
+byte 5::
+
+   bit   7   6   5   4   3   2   1   0
+        y7  y6  y5  y4  y3  y2  y1  y0
+
+        y11..y0 = absolute y value (vertical)
+
+Two finger touch
+^^^^^^^^^^^^^^^^
+
+The packet format is exactly the same for two finger touch, except the hardware
+sends two 6 byte packets. The first packet contains data for the first finger,
+the second packet has data for the second finger. So for two finger touch a
+total of 12 bytes are sent.
+
+Hardware version 4
+~~~~~~~~~~~~~~~~~~
+
+Registers
+---------
+
+* reg_07::
+
+   bit   7   6   5   4   3   2   1   0
+         0   0   0   0   0   0   0   A
+
+         A: 1 = enable absolute tracking
+
+Native absolute mode 6 byte packet format
+-----------------------------------------
+
+v4 hardware is a true multitouch touchpad, capable of tracking up to 5 fingers.
+Unfortunately, due to PS/2's limited bandwidth, its packet format is rather
+complex.
+
+Whenever the numbers or identities of the fingers changes, the hardware sends a
+status packet to indicate how many and which fingers is on touchpad, followed by
+head packets or motion packets. A head packet contains data of finger id, finger
+position (absolute x, y values), width, and pressure. A motion packet contains
+two fingers' position delta.
+
+For example, when status packet tells there are 2 fingers on touchpad, then we
+can expect two following head packets. If the finger status doesn't change,
+the following packets would be motion packets, only sending delta of finger
+position, until we receive a status packet.
+
+One exception is one finger touch. when a status packet tells us there is only
+one finger, the hardware would just send head packets afterwards.
+
+Status packet
+^^^^^^^^^^^^^
+
+byte 0::
+
+   bit   7   6   5   4   3   2   1   0
+         .   .   .   .   0   1   R   L
+
+         L, R = 1 when Left, Right mouse button pressed
+
+byte 1::
+
+   bit   7   6   5   4   3   2   1   0
+         .   .   . ft4 ft3 ft2 ft1 ft0
+
+         ft4 ft3 ft2 ft1 ft0 ftn = 1 when finger n is on touchpad
+
+byte 2::
+
+   not used
+
+byte 3::
+
+   bit   7   6   5   4   3   2   1   0
+         .   .   .   1   0   0   0   0
+
+         constant bits
+
+byte 4::
+
+   bit   7   6   5   4   3   2   1   0
+         p   .   .   .   .   .   .   .
+
+         p = 1 for palm
+
+byte 5::
+
+   not used
+
+Head packet
+^^^^^^^^^^^
+
+byte 0::
+
+   bit   7   6   5   4   3   2   1   0
+        w3  w2  w1  w0   0   1   R   L
+
+        L, R = 1 when Left, Right mouse button pressed
+        w3..w0 = finger width (spans how many trace lines)
+
+byte 1::
+
+   bit   7   6   5   4   3   2   1   0
+        p7  p6  p5  p4 x11 x10  x9  x8
+
+byte 2::
+
+   bit   7   6   5   4   3   2   1   0
+        x7  x6  x5  x4  x3  x2  x1  x0
+
+        x11..x0 = absolute x value (horizontal)
+
+byte 3::
+
+   bit   7   6   5   4   3   2   1   0
+       id2 id1 id0   1   0   0   0   1
+
+       id2..id0 = finger id
+
+byte 4::
+
+   bit   7   6   5   4   3   2   1   0
+        p3  p1  p2  p0  y11 y10 y9  y8
+
+        p7..p0 = pressure
+
+byte 5::
+
+   bit   7   6   5   4   3   2   1   0
+        y7  y6  y5  y4  y3  y2  y1  y0
+
+        y11..y0 = absolute y value (vertical)
+
+Motion packet
+^^^^^^^^^^^^^
+
+byte 0::
+
+   bit   7   6   5   4   3   2   1   0
+       id2 id1 id0   w   0   1   R   L
+
+       L, R = 1 when Left, Right mouse button pressed
+       id2..id0 = finger id
+       w = 1 when delta overflows (> 127 or < -128), in this case
+       firmware sends us (delta x / 5) and (delta y  / 5)
+
+byte 1::
+
+   bit   7   6   5   4   3   2   1   0
+        x7  x6  x5  x4  x3  x2  x1  x0
+
+        x7..x0 = delta x (two's complement)
+
+byte 2::
+
+   bit   7   6   5   4   3   2   1   0
+        y7  y6  y5  y4  y3  y2  y1  y0
+
+        y7..y0 = delta y (two's complement)
+
+byte 3::
+
+   bit   7   6   5   4   3   2   1   0
+       id2 id1 id0   1   0   0   1   0
+
+       id2..id0 = finger id
+
+byte 4::
+
+   bit   7   6   5   4   3   2   1   0
+        x7  x6  x5  x4  x3  x2  x1  x0
+
+        x7..x0 = delta x (two's complement)
+
+byte 5::
+
+   bit   7   6   5   4   3   2   1   0
+        y7  y6  y5  y4  y3  y2  y1  y0
+
+        y7..y0 = delta y (two's complement)
+
+        byte 0 ~ 2 for one finger
+        byte 3 ~ 5 for another
+
+
+Trackpoint (for Hardware version 3 and 4)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Registers
+---------
+
+No special registers have been identified.
+
+Native relative mode 6 byte packet format
+-----------------------------------------
+
+Status Packet
+^^^^^^^^^^^^^
+
+byte 0::
+
+   bit   7   6   5   4   3   2   1   0
+         0   0  sx  sy   0   M   R   L
+
+byte 1::
+
+   bit   7   6   5   4   3   2   1   0
+       ~sx   0   0   0   0   0   0   0
+
+byte 2::
+
+   bit   7   6   5   4   3   2   1   0
+       ~sy   0   0   0   0   0   0   0
+
+byte 3::
+
+   bit   7   6   5   4   3   2   1   0
+         0   0 ~sy ~sx   0   1   1   0
+
+byte 4::
+
+   bit   7   6   5   4   3   2   1   0
+        x7  x6  x5  x4  x3  x2  x1  x0
+
+byte 5::
+
+   bit   7   6   5   4   3   2   1   0
+        y7  y6  y5  y4  y3  y2  y1  y0
+
+
+         x and y are written in two's complement spread
+             over 9 bits with sx/sy the relative top bit and
+             x7..x0 and y7..y0 the lower bits.
+        ~sx is the inverse of sx, ~sy is the inverse of sy.
+         The sign of y is opposite to what the input driver
+             expects for a relative movement
diff --git a/Documentation/input/devices/gpio-tilt.rst b/Documentation/input/devices/gpio-tilt.rst
new file mode 100644 (file)
index 0000000..fa6e645
--- /dev/null
@@ -0,0 +1,103 @@
+Driver for tilt-switches connected via GPIOs
+============================================
+
+Generic driver to read data from tilt switches connected via gpios.
+Orientation can be provided by one or more than one tilt switches,
+i.e. each tilt switch providing one axis, and the number of axes
+is also not limited.
+
+
+Data structures
+---------------
+
+The array of struct gpio in the gpios field is used to list the gpios
+that represent the current tilt state.
+
+The array of struct gpio_tilt_axis describes the axes that are reported
+to the input system. The values set therein are used for the
+input_set_abs_params calls needed to init the axes.
+
+The array of struct gpio_tilt_state maps gpio states to the corresponding
+values to report. The gpio state is represented as a bitfield where the
+bit-index corresponds to the index of the gpio in the struct gpio array.
+In the same manner the values stored in the axes array correspond to
+the elements of the gpio_tilt_axis-array.
+
+
+Example
+-------
+
+Example configuration for a single TS1003 tilt switch that rotates around
+one axis in 4 steps and emits the current tilt via two GPIOs::
+
+    static int sg060_tilt_enable(struct device *dev) {
+           /* code to enable the sensors */
+    };
+
+    static void sg060_tilt_disable(struct device *dev) {
+           /* code to disable the sensors */
+    };
+
+    static struct gpio sg060_tilt_gpios[] = {
+           { SG060_TILT_GPIO_SENSOR1, GPIOF_IN, "tilt_sensor1" },
+           { SG060_TILT_GPIO_SENSOR2, GPIOF_IN, "tilt_sensor2" },
+    };
+
+    static struct gpio_tilt_state sg060_tilt_states[] = {
+           {
+                   .gpios = (0 << 1) | (0 << 0),
+                   .axes = (int[]) {
+                           0,
+                   },
+           }, {
+                   .gpios = (0 << 1) | (1 << 0),
+                   .axes = (int[]) {
+                           1, /* 90 degrees */
+                   },
+           }, {
+                   .gpios = (1 << 1) | (1 << 0),
+                   .axes = (int[]) {
+                           2, /* 180 degrees */
+                   },
+           }, {
+                   .gpios = (1 << 1) | (0 << 0),
+                   .axes = (int[]) {
+                           3, /* 270 degrees */
+                   },
+           },
+    };
+
+    static struct gpio_tilt_axis sg060_tilt_axes[] = {
+           {
+                   .axis = ABS_RY,
+                   .min = 0,
+                   .max = 3,
+                   .fuzz = 0,
+                   .flat = 0,
+           },
+    };
+
+    static struct gpio_tilt_platform_data sg060_tilt_pdata= {
+           .gpios = sg060_tilt_gpios,
+           .nr_gpios = ARRAY_SIZE(sg060_tilt_gpios),
+
+           .axes = sg060_tilt_axes,
+           .nr_axes = ARRAY_SIZE(sg060_tilt_axes),
+
+           .states = sg060_tilt_states,
+           .nr_states = ARRAY_SIZE(sg060_tilt_states),
+
+           .debounce_interval = 100,
+
+           .poll_interval = 1000,
+           .enable = sg060_tilt_enable,
+           .disable = sg060_tilt_disable,
+    };
+
+    static struct platform_device sg060_device_tilt = {
+           .name = "gpio-tilt-polled",
+           .id = -1,
+           .dev = {
+                   .platform_data = &sg060_tilt_pdata,
+           },
+    };
diff --git a/Documentation/input/devices/iforce-protocol.rst b/Documentation/input/devices/iforce-protocol.rst
new file mode 100644 (file)
index 0000000..8634bea
--- /dev/null
@@ -0,0 +1,381 @@
+===============
+Iforce Protocol
+===============
+
+:Author: Johann Deneux <johann.deneux@gmail.com>
+
+Home page at `<http://web.archive.org/web/*/http://www.esil.univ-mrs.fr>`_
+
+:Additions: by Vojtech Pavlik.
+
+
+Introduction
+============
+
+This document describes what I managed to discover about the protocol used to
+specify force effects to I-Force 2.0 devices.  None of this information comes
+from Immerse. That's why you should not trust what is written in this
+document. This document is intended to help understanding the protocol.
+This is not a reference. Comments and corrections are welcome.  To contact me,
+send an email to: johann.deneux@gmail.com
+
+.. warning::
+
+    I shall not be held responsible for any damage or harm caused if you try to
+    send data to your I-Force device based on what you read in this document.
+
+Preliminary Notes
+=================
+
+All values are hexadecimal with big-endian encoding (msb on the left). Beware,
+values inside packets are encoded using little-endian.  Bytes whose roles are
+unknown are marked ???  Information that needs deeper inspection is marked (?)
+
+General form of a packet
+------------------------
+
+This is how packets look when the device uses the rs232 to communicate.
+
+== == === ==== ==
+2B OP LEN DATA CS
+== == === ==== ==
+
+CS is the checksum. It is equal to the exclusive or of all bytes.
+
+When using USB:
+
+== ====
+OP DATA
+== ====
+
+The 2B, LEN and CS fields have disappeared, probably because USB handles
+frames and data corruption is handled or unsignificant.
+
+First, I describe effects that are sent by the device to the computer
+
+Device input state
+==================
+
+This packet is used to indicate the state of each button and the value of each
+axis::
+
+    OP= 01 for a joystick, 03 for a wheel
+    LEN= Varies from device to device
+    00 X-Axis lsb
+    01 X-Axis msb
+    02 Y-Axis lsb, or gas pedal for a wheel
+    03 Y-Axis msb, or brake pedal for a wheel
+    04 Throttle
+    05 Buttons
+    06 Lower 4 bits: Buttons
+       Upper 4 bits: Hat
+    07 Rudder
+
+Device effects states
+=====================
+
+::
+
+    OP= 02
+    LEN= Varies
+    00 ? Bit 1 (Value 2) is the value of the deadman switch
+    01 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id.
+    02 ??
+    03 Address of parameter block changed (lsb)
+    04 Address of parameter block changed (msb)
+    05 Address of second parameter block changed (lsb)
+    ... depending on the number of parameter blocks updated
+
+Force effect
+------------
+
+::
+
+    OP=  01
+    LEN= 0e
+    00 Channel (when playing several effects at the same time, each must
+                be assigned a channel)
+    01 Wave form
+           Val 00 Constant
+           Val 20 Square
+           Val 21 Triangle
+           Val 22 Sine
+           Val 23 Sawtooth up
+           Val 24 Sawtooth down
+           Val 40 Spring (Force = f(pos))
+           Val 41 Friction (Force = f(velocity)) and Inertia
+                  (Force = f(acceleration))
+
+
+    02 Axes affected and trigger
+           Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction
+                   Val 4 = X axis only. Byte 05 must contain 5a
+                   Val 8 = Y axis only. Byte 05 must contain b4
+                   Val c = X and Y axes. Bytes 05 must contain 60
+           Bits 0-3: Val 0 = No trigger
+                   Val x+1 = Button x triggers the effect
+           When the whole byte is 0, cancel the previously set trigger
+
+    03-04 Duration of effect (little endian encoding, in ms)
+
+    05 Direction of effect, if applicable. Else, see 02 for value to assign.
+
+    06-07 Minimum time between triggering.
+
+    08-09 Address of periodicity or magnitude parameters
+    0a-0b Address of attack and fade parameters, or ffff if none.
+    *or*
+    08-09 Address of interactive parameters for X-axis,
+          or ffff if not applicable
+    0a-0b Address of interactive parameters for Y-axis,
+         or ffff if not applicable
+
+    0c-0d Delay before execution of effect (little endian encoding, in ms)
+
+
+Time based parameters
+---------------------
+
+Attack and fade
+^^^^^^^^^^^^^^^
+
+::
+
+    OP=  02
+    LEN= 08
+    00-01 Address where to store the parameters
+    02-03 Duration of attack (little endian encoding, in ms)
+    04 Level at end of attack. Signed byte.
+    05-06 Duration of fade.
+    07 Level at end of fade.
+
+Magnitude
+^^^^^^^^^
+
+::
+
+    OP=  03
+    LEN= 03
+    00-01 Address
+    02 Level. Signed byte.
+
+Periodicity
+^^^^^^^^^^^
+
+::
+
+    OP=  04
+    LEN= 07
+    00-01 Address
+    02 Magnitude. Signed byte.
+    03 Offset. Signed byte.
+    04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
+    05-06 Period (little endian encoding, in ms)
+
+Interactive parameters
+----------------------
+
+::
+
+    OP=  05
+    LEN= 0a
+    00-01 Address
+    02 Positive Coeff
+    03 Negative Coeff
+    04+05 Offset (center)
+    06+07 Dead band (Val 01F4 = 5000 (decimal))
+    08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal))
+    09 Negative saturation
+
+The encoding is a bit funny here: For coeffs, these are signed values. The
+maximum value is 64 (100 decimal), the min is 9c.
+For the offset, the minimum value is FE0C, the maximum value is 01F4.
+For the deadband, the minimum value is 0, the max is 03E8.
+
+Controls
+--------
+
+::
+
+    OP=  41
+    LEN= 03
+    00 Channel
+    01 Start/Stop
+           Val 00: Stop
+           Val 01: Start and play once.
+           Val 41: Start and play n times (See byte 02 below)
+    02 Number of iterations n.
+
+Init
+----
+
+
+Querying features
+^^^^^^^^^^^^^^^^^
+::
+
+    OP=  ff
+    Query command. Length varies according to the query type.
+    The general format of this packet is:
+    ff 01 QUERY [INDEX] CHECKSUM
+    responses are of the same form:
+    FF LEN QUERY VALUE_QUERIED CHECKSUM2
+    where LEN = 1 + length(VALUE_QUERIED)
+
+Query ram size
+~~~~~~~~~~~~~~
+
+::
+
+    QUERY = 42 ('B'uffer size)
+
+The device should reply with the same packet plus two additional bytes
+containing the size of the memory:
+ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
+
+Query number of effects
+~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    QUERY = 4e ('N'umber of effects)
+
+The device should respond by sending the number of effects that can be played
+at the same time (one byte)
+ff 02 4e 14 CS would stand for 20 effects.
+
+Vendor's id
+~~~~~~~~~~~
+
+::
+
+    QUERY = 4d ('M'anufacturer)
+
+Query the vendors'id (2 bytes)
+
+Product id
+~~~~~~~~~~
+
+::
+
+    QUERY = 50 ('P'roduct)
+
+Query the product id (2 bytes)
+
+Open device
+~~~~~~~~~~~
+
+::
+
+    QUERY = 4f ('O'pen)
+
+No data returned.
+
+Close device
+~~~~~~~~~~~~
+
+::
+
+    QUERY = 43 ('C')lose
+
+No data returned.
+
+Query effect
+~~~~~~~~~~~~
+
+::
+
+    QUERY = 45 ('E')
+
+Send effect type.
+Returns nonzero if supported (2 bytes)
+
+Firmware Version
+~~~~~~~~~~~~~~~~
+
+::
+
+    QUERY = 56 ('V'ersion)
+
+Sends back 3 bytes - major, minor, subminor
+
+Initialisation of the device
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set Control
+~~~~~~~~~~~
+
+.. note::
+    Device dependent, can be different on different models!
+
+::
+
+    OP=  40 <idx> <val> [<val>]
+    LEN= 2 or 3
+    00 Idx
+       Idx 00 Set dead zone (0..2048)
+       Idx 01 Ignore Deadman sensor (0..1)
+       Idx 02 Enable comm watchdog (0..1)
+       Idx 03 Set the strength of the spring (0..100)
+       Idx 04 Enable or disable the spring (0/1)
+       Idx 05 Set axis saturation threshold (0..2048)
+
+Set Effect State
+~~~~~~~~~~~~~~~~
+
+::
+
+    OP=  42 <val>
+    LEN= 1
+    00 State
+       Bit 3 Pause force feedback
+       Bit 2 Enable force feedback
+       Bit 0 Stop all effects
+
+Set overall
+~~~~~~~~~~~
+
+::
+
+    OP=  43 <val>
+    LEN= 1
+    00 Gain
+       Val 00 = 0%
+       Val 40 = 50%
+       Val 80 = 100%
+
+Parameter memory
+----------------
+
+Each device has a certain amount of memory to store parameters of effects.
+The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below
+is the amount of memory apparently needed for every set of parameters:
+
+ - period : 0c
+ - magnitude : 02
+ - attack and fade : 0e
+ - interactive : 08
+
+Appendix: How to study the protocol?
+====================================
+
+1. Generate effects using the force editor provided with the DirectX SDK, or
+use Immersion Studio (freely available at their web site in the developer section:
+www.immersion.com)
+2. Start a soft spying RS232 or USB (depending on where you connected your
+joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
+3. Play the effect, and watch what happens on the spy screen.
+
+A few words about ComPortSpy:
+At first glance, this software seems, hum, well... buggy. In fact, data appear with a
+few seconds latency. Personally, I restart it every time I play an effect.
+Remember it's free (as in free beer) and alpha!
+
+URLS
+====
+
+Check http://www.immerse.com for Immersion Studio,
+and http://www.fcoder.com for ComPortSpy.
+
+
+I-Force is trademark of Immersion Corp.
diff --git a/Documentation/input/devices/index.rst b/Documentation/input/devices/index.rst
new file mode 100644 (file)
index 0000000..95a4537
--- /dev/null
@@ -0,0 +1,19 @@
+Driver-specific documentation
+=============================
+
+This section provides information about various devices supported by the
+Linux kernel, their protocols, and driver details.
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+   :glob:
+
+   *
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/input/devices/joystick-parport.rst b/Documentation/input/devices/joystick-parport.rst
new file mode 100644 (file)
index 0000000..e8ce16e
--- /dev/null
@@ -0,0 +1,611 @@
+.. include:: <isonum.txt>
+
+.. _joystick-parport:
+
+==============================
+Parallel Port Joystick Drivers
+==============================
+
+:Copyright: |copy| 1998-2000 Vojtech Pavlik <vojtech@ucw.cz>
+:Copyright: |copy| 1998 Andree Borrmann <a.borrmann@tu-bs.de>
+
+
+Sponsored by SuSE
+
+Disclaimer
+==========
+
+Any information in this file is provided as-is, without any guarantee that
+it will be true. So, use it at your own risk. The possible damages that can
+happen include burning your parallel port, and/or the sticks and joystick
+and maybe even more. Like when a lightning kills you it is not our problem.
+
+Introduction
+============
+
+The joystick parport drivers are used for joysticks and gamepads not
+originally designed for PCs and other computers Linux runs on. Because of
+that, PCs usually lack the right ports to connect these devices to. Parallel
+port, because of its ability to change single bits at will, and providing
+both output and input bits is the most suitable port on the PC for
+connecting such devices.
+
+Devices supported
+=================
+
+Many console and 8-bit computer gamepads and joysticks are supported. The
+following subsections discuss usage of each.
+
+NES and SNES
+------------
+
+The Nintendo Entertainment System and Super Nintendo Entertainment System
+gamepads are widely available, and easy to get. Also, they are quite easy to
+connect to a PC, and don't need much processing speed (108 us for NES and
+165 us for SNES, compared to about 1000 us for PC gamepads) to communicate
+with them.
+
+All NES and SNES use the same synchronous serial protocol, clocked from
+the computer's side (and thus timing insensitive). To allow up to 5 NES
+and/or SNES gamepads and/or SNES mice connected to the parallel port at once,
+the output lines of the parallel port are shared, while one of 5 available
+input lines is assigned to each gamepad.
+
+This protocol is handled by the gamecon.c driver, so that's the one
+you'll use for NES, SNES gamepads and SNES mice.
+
+The main problem with PC parallel ports is that they don't have +5V power
+source on any of their pins. So, if you want a reliable source of power
+for your pads, use either keyboard or joystick port, and make a pass-through
+cable. You can also pull the power directly from the power supply (the red
+wire is +5V).
+
+If you want to use the parallel port only, you can take the power is from
+some data pin. For most gamepad and parport implementations only one pin is
+needed, and I'd recommend pin 9 for that, the highest data bit. On the other
+hand, if you are not planning to use anything else than NES / SNES on the
+port, anything between and including pin 4 and pin 9 will work::
+
+    (pin 9) -----> Power
+
+Unfortunately, there are pads that need a lot more of power, and parallel
+ports that can't give much current through the data pins. If this is your
+case, you'll need to use diodes (as a prevention of destroying your parallel
+port), and combine the currents of two or more data bits together::
+
+             Diodes
+    (pin 9) ----|>|-------+------> Power
+                       |
+    (pin 8) ----|>|-------+
+                       |
+    (pin 7) ----|>|-------+
+                       |
+    <and so on>         :
+                       |
+    (pin 4) ----|>|-------+
+
+Ground is quite easy. On PC's parallel port the ground is on any of the
+pins from pin 18 to pin 25. So use any pin of these you like for the ground::
+
+    (pin 18) -----> Ground
+
+NES and SNES pads have two input bits, Clock and Latch, which drive the
+serial transfer. These are connected to pins 2 and 3 of the parallel port,
+respectively::
+
+    (pin 2) -----> Clock
+    (pin 3) -----> Latch
+
+And the last thing is the NES / SNES data wire. Only that isn't shared and
+each pad needs its own data pin. The parallel port pins are::
+
+    (pin 10) -----> Pad 1 data
+    (pin 11) -----> Pad 2 data
+    (pin 12) -----> Pad 3 data
+    (pin 13) -----> Pad 4 data
+    (pin 15) -----> Pad 5 data
+
+Note that pin 14 is not used, since it is not an input pin on the parallel
+port.
+
+This is everything you need on the PC's side of the connection, now on to
+the gamepads side. The NES and SNES have different connectors. Also, there
+are quite a lot of NES clones, and because Nintendo used proprietary
+connectors for their machines, the cloners couldn't and used standard D-Cannon
+connectors. Anyway, if you've got a gamepad, and it has buttons A, B, Turbo
+A, Turbo B, Select and Start, and is connected through 5 wires, then it is
+either a NES or NES clone and will work with this connection. SNES gamepads
+also use 5 wires, but have more buttons. They will work as well, of course::
+
+  Pinout for NES gamepads                 Pinout for SNES gamepads and mice
+
+             +----> Power                   +-----------------------\
+             |                            7 | o  o  o  o |  x  x  o  | 1
+   5 +---------+  7                         +-----------------------/
+     | x  x  o   \                            |  |  |  |          |
+     | o  o  o  o |                           |  |  |  |          +-> Ground
+   4 +------------+ 1                         |  |  |  +------------> Data
+       |  |  |  |                             |  |  +---------------> Latch
+       |  |  |  +-> Ground                    |  +------------------> Clock
+       |  |  +----> Clock                     +---------------------> Power
+       |  +-------> Latch
+       +----------> Data
+
+  Pinout for NES clone (db9) gamepads     Pinout for NES clone (db15) gamepads
+
+        +---------> Clock                    +-----------------> Data
+        | +-------> Latch                    |             +---> Ground
+        | | +-----> Data                     |             |
+        | | |                              ___________________
+    _____________                        8 \ o x x x x x x o / 1
+  5 \ x o o o x / 1                         \ o x x o x x o /
+     \ x o x o /                          15 `~~~~~~~~~~~~~' 9
+    9 `~~~~~~~' 6                             |     |     |
+         |   |                                |     |     +----> Clock
+         |   +----> Power                     |     +----------> Latch
+         +--------> Ground                    +----------------> Power
+
+Multisystem joysticks
+---------------------
+
+In the era of 8-bit machines, there was something like de-facto standard
+for joystick ports. They were all digital, and all used D-Cannon 9 pin
+connectors (db9). Because of that, a single joystick could be used without
+hassle on Atari (130, 800XE, 800XL, 2600, 7200), Amiga, Commodore C64,
+Amstrad CPC, Sinclair ZX Spectrum and many other machines. That's why these
+joysticks are called "Multisystem".
+
+Now their pinout::
+
+        +---------> Right
+        | +-------> Left
+        | | +-----> Down
+        | | | +---> Up
+        | | | |
+    _____________
+  5 \ x o o o o / 1
+     \ x o x o /
+    9 `~~~~~~~' 6
+         |   |
+         |   +----> Button
+         +--------> Ground
+
+However, as time passed, extensions to this standard developed, and these
+were not compatible with each other::
+
+
+          Atari 130, 800/XL/XE                   MSX
+
+                                           +-----------> Power
+        +---------> Right                  | +---------> Right
+        | +-------> Left                   | | +-------> Left
+        | | +-----> Down                   | | | +-----> Down
+        | | | +---> Up                     | | | | +---> Up
+        | | | |                            | | | | |
+    _____________                        _____________
+  5 \ x o o o o / 1                    5 \ o o o o o / 1
+     \ x o o o /                          \ o o o o /
+    9 `~~~~~~~' 6                        9 `~~~~~~~' 6
+         | | |                              | | | |
+         | | +----> Button                  | | | +----> Button 1
+         | +------> Power                   | | +------> Button 2
+         +--------> Ground                  | +--------> Output 3
+                                            +----------> Ground
+
+          Amstrad CPC                           Commodore C64
+
+                                           +-----------> Analog Y
+        +---------> Right                  | +---------> Right
+        | +-------> Left                   | | +-------> Left
+        | | +-----> Down                   | | | +-----> Down
+        | | | +---> Up                     | | | | +---> Up
+        | | | |                            | | | | |
+    _____________                        _____________
+  5 \ x o o o o / 1                    5 \ o o o o o / 1
+     \ x o o o /                          \ o o o o /
+    9 `~~~~~~~' 6                        9 `~~~~~~~' 6
+         | | |                              | | | |
+         | | +----> Button 1                | | | +----> Button
+         | +------> Button 2                | | +------> Power
+         +--------> Ground                  | +--------> Ground
+                                            +----------> Analog X
+
+          Sinclair Spectrum +2A/+3           Amiga 1200
+
+      +-----------> Up                     +-----------> Button 3
+      | +---------> Fire                   | +---------> Right
+      | |                                  | | +-------> Left
+      | |   +-----> Ground                 | | | +-----> Down
+      | |   |                              | | | | +---> Up
+      | |   |                              | | | | |
+    _____________                        _____________
+  5 \ o o x o x / 1                    5 \ o o o o o / 1
+     \ o o o o /                          \ o o o o /
+    9 `~~~~~~~' 6                        9 `~~~~~~~' 6
+       | | | |                              | | | |
+       | | | +----> Right                   | | | +----> Button 1
+       | | +------> Left                    | | +------> Power
+       | +--------> Ground                  | +--------> Ground
+       +----------> Down                    +----------> Button 2
+
+  And there were many others.
+
+Multisystem joysticks using db9.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For the Multisystem joysticks, and their derivatives, the db9.c driver
+was written. It allows only one joystick / gamepad per parallel port, but
+the interface is easy to build and works with almost anything.
+
+For the basic 1-button Multisystem joystick you connect its wires to the
+parallel port like this::
+
+    (pin  1) -----> Power
+    (pin 18) -----> Ground
+
+    (pin  2) -----> Up
+    (pin  3) -----> Down
+    (pin  4) -----> Left
+    (pin  5) -----> Right
+    (pin  6) -----> Button 1
+
+However, if the joystick is switch based (eg. clicks when you move it),
+you might or might not, depending on your parallel port, need 10 kOhm pullup
+resistors on each of the direction and button signals, like this::
+
+    (pin 2) ------------+------> Up
+              Resistor  |
+    (pin 1) --[10kOhm]--+
+
+Try without, and if it doesn't work, add them. For TTL based joysticks /
+gamepads the pullups are not needed.
+
+For joysticks with two buttons you connect the second button to pin 7 on
+the parallel port::
+
+    (pin 7) -----> Button 2
+
+And that's it.
+
+On a side note, if you have already built a different adapter for use with
+the digital joystick driver 0.8.0.2, this is also supported by the db9.c
+driver, as device type 8. (See section 3.2)
+
+Multisystem joysticks using gamecon.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For some people just one joystick per parallel port is not enough, and/or
+want to use them on one parallel port together with NES/SNES/PSX pads. This is
+possible using the gamecon.c. It supports up to 5 devices of the above types,
+including 1 and 2 buttons Multisystem joysticks.
+
+However, there is nothing for free. To allow more sticks to be used at
+once, you need the sticks to be purely switch based (that is non-TTL), and
+not to need power. Just a plain simple six switches inside. If your
+joystick can do more (eg. turbofire) you'll need to disable it totally first
+if you want to use gamecon.c.
+
+Also, the connection is a bit more complex. You'll need a bunch of diodes,
+and one pullup resistor. First, you connect the Directions and the button
+the same as for db9, however with the diodes between::
+
+                Diodes
+    (pin 2) -----|<|----> Up
+    (pin 3) -----|<|----> Down
+    (pin 4) -----|<|----> Left
+    (pin 5) -----|<|----> Right
+    (pin 6) -----|<|----> Button 1
+
+For two button sticks you also connect the other button::
+
+    (pin 7) -----|<|----> Button 2
+
+And finally, you connect the Ground wire of the joystick, like done in
+this little schematic to Power and Data on the parallel port, as described
+for the NES / SNES pads in section 2.1 of this file - that is, one data pin
+for each joystick. The power source is shared::
+
+    Data    ------------+-----> Ground
+              Resistor  |
+    Power   --[10kOhm]--+
+
+And that's all, here we go!
+
+Multisystem joysticks using turbografx.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The TurboGraFX interface, designed by
+
+       Steffen Schwenke <schwenke@burg-halle.de>
+
+allows up to 7 Multisystem joysticks connected to the parallel port. In
+Steffen's version, there is support for up to 5 buttons per joystick.  However,
+since this doesn't work reliably on all parallel ports, the turbografx.c driver
+supports only one button per joystick. For more information on how to build the
+interface, see:
+
+       http://www2.burg-halle.de/~schwenke/parport.html
+
+Sony Playstation
+----------------
+
+The PSX controller is supported by the gamecon.c. Pinout of the PSX
+controller (compatible with DirectPadPro)::
+
+    +---------+---------+---------+
+  9 | o  o  o | o  o  o | o  o  o | 1               parallel
+     \________|_________|________/                  port pins
+      |  |      |  |  |   |
+      |  |      |  |  |   +-------->  Clock    ---  (4)
+      |  |      |  |  +------------>  Select   ---  (3)
+      |  |      |  +--------------->  Power    ---  (5-9)
+      |  |      +------------------>  Ground   ---  (18-25)
+      |  +------------------------->  Command  ---  (2)
+      +---------------------------->  Data     ---  (one of 10,11,12,13,15)
+
+The driver supports these controllers:
+
+ * Standard PSX Pad
+ * NegCon PSX Pad
+ * Analog PSX Pad (red mode)
+ * Analog PSX Pad (green mode)
+ * PSX Rumble Pad
+ * PSX DDR Pad
+
+Sega
+----
+
+All the Sega controllers are more or less based on the standard 2-button
+Multisystem joystick. However, since they don't use switches and use TTL
+logic, the only driver usable with them is the db9.c driver.
+
+Sega Master System
+~~~~~~~~~~~~~~~~~~
+
+The SMS gamepads are almost exactly the same as normal 2-button
+Multisystem joysticks. Set the driver to Multi2 mode, use the corresponding
+parallel port pins, and the following schematic::
+
+      +-----------> Power
+      | +---------> Right
+      | | +-------> Left
+      | | | +-----> Down
+      | | | | +---> Up
+      | | | | |
+    _____________
+  5 \ o o o o o / 1
+     \ o o x o /
+    9 `~~~~~~~' 6
+       | |   |
+       | |   +----> Button 1
+       | +--------> Ground
+       +----------> Button 2
+
+Sega Genesis aka MegaDrive
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Sega Genesis (in Europe sold as Sega MegaDrive) pads are an extension
+to the Sega Master System pads. They use more buttons (3+1, 5+1, 6+1).  Use
+the following schematic::
+
+        +-----------> Power
+        | +---------> Right
+        | | +-------> Left
+        | | | +-----> Down
+        | | | | +---> Up
+        | | | | |
+      _____________
+    5 \ o o o o o / 1
+       \ o o o o /
+      9 `~~~~~~~' 6
+        | | | |
+        | | | +----> Button 1
+        | | +------> Select
+        | +--------> Ground
+        +----------> Button 2
+
+The Select pin goes to pin 14 on the parallel port::
+
+    (pin 14) -----> Select
+
+The rest is the same as for Multi2 joysticks using db9.c
+
+Sega Saturn
+~~~~~~~~~~~
+
+Sega Saturn has eight buttons, and to transfer that, without hacks like
+Genesis 6 pads use, it needs one more select pin. Anyway, it is still
+handled by the db9.c driver. Its pinout is very different from anything
+else.  Use this schematic::
+
+      +-----------> Select 1
+      | +---------> Power
+      | | +-------> Up
+      | | | +-----> Down
+      | | | | +---> Ground
+      | | | | |
+    _____________
+  5 \ o o o o o / 1
+     \ o o o o /
+    9 `~~~~~~~' 6
+       | | | |
+       | | | +----> Select 2
+       | | +------> Right
+       | +--------> Left
+       +----------> Power
+
+Select 1 is pin 14 on the parallel port, Select 2 is pin 16 on the
+parallel port::
+
+    (pin 14) -----> Select 1
+    (pin 16) -----> Select 2
+
+The other pins (Up, Down, Right, Left, Power, Ground) are the same as for
+Multi joysticks using db9.c
+
+Amiga CD32
+----------
+
+Amiga CD32 joypad uses the following pinout::
+
+        +-----------> Button 3
+        | +---------> Right
+        | | +-------> Left
+        | | | +-----> Down
+        | | | | +---> Up
+        | | | | |
+      _____________
+    5 \ o o o o o / 1
+       \ o o o o /
+      9 `~~~~~~~' 6
+        | | | |
+        | | | +----> Button 1
+        | | +------> Power
+        | +--------> Ground
+        +----------> Button 2
+
+It can be connected to the parallel port and driven by db9.c driver. It needs the following wiring:
+
+       ============    =============
+       CD32 pad        Parallel port
+       ============    =============
+       1 (Up)           2 (D0)
+       2 (Down)         3 (D1)
+       3 (Left)         4 (D2)
+       4 (Right)        5 (D3)
+       5 (Button 3)    14 (AUTOFD)
+       6 (Button 1)    17 (SELIN)
+       7 (+5V)          1 (STROBE)
+       8 (Gnd)         18 (Gnd)
+       9 (Button 2)     7 (D5)
+       ============    =============
+
+The drivers
+===========
+
+There are three drivers for the parallel port interfaces. Each, as
+described above, allows to connect a different group of joysticks and pads.
+Here are described their command lines:
+
+gamecon.c
+---------
+
+Using gamecon.c you can connect up to five devices to one parallel port. It
+uses the following kernel/module command line::
+
+       gamecon.map=port,pad1,pad2,pad3,pad4,pad5
+
+Where ``port`` the number of the parport interface (eg. 0 for parport0).
+
+And ``pad1`` to ``pad5`` are pad types connected to different data input pins
+(10,11,12,13,15), as described in section 2.1 of this file.
+
+The types are:
+
+       ===== =============================
+       Type  Joystick/Pad
+       ===== =============================
+         0   None
+         1   SNES pad
+         2   NES pad
+         4   Multisystem 1-button joystick
+         5   Multisystem 2-button joystick
+         6   N64 pad
+         7   Sony PSX controller
+         8   Sony PSX DDR controller
+         9   SNES mouse
+       ===== =============================
+
+The exact type of the PSX controller type is autoprobed when used, so
+hot swapping should work (but is not recommended).
+
+Should you want to use more than one of parallel ports at once, you can use
+gamecon.map2 and gamecon.map3 as additional command line parameters for two
+more parallel ports.
+
+There are two options specific to PSX driver portion.  gamecon.psx_delay sets
+the command delay when talking to the controllers. The default of 25 should
+work but you can try lowering it for better performance. If your pads don't
+respond try raising it until they work. Setting the type to 8 allows the
+driver to be used with Dance Dance Revolution or similar games. Arrow keys are
+registered as key presses instead of X and Y axes.
+
+db9.c
+-----
+
+Apart from making an interface, there is nothing difficult on using the
+db9.c driver. It uses the following kernel/module command line::
+
+       db9.dev=port,type
+
+Where ``port`` is the number of the parport interface (eg. 0 for parport0).
+
+Caveat here: This driver only works on bidirectional parallel ports. If
+your parallel port is recent enough, you should have no trouble with this.
+Old parallel ports may not have this feature.
+
+``Type`` is the type of joystick or pad attached:
+
+       ===== ======================================================
+       Type  Joystick/Pad
+       ===== ======================================================
+         0   None
+         1   Multisystem 1-button joystick
+         2   Multisystem 2-button joystick
+         3   Genesis pad (3+1 buttons)
+         5   Genesis pad (5+1 buttons)
+         6   Genesis pad (6+2 buttons)
+         7   Saturn pad (8 buttons)
+         8   Multisystem 1-button joystick (v0.8.0.2 pin-out)
+         9   Two Multisystem 1-button joysticks (v0.8.0.2 pin-out)
+        10   Amiga CD32 pad
+       ===== ======================================================
+
+Should you want to use more than one of these joysticks/pads at once, you
+can use db9.dev2 and db9.dev3 as additional command line parameters for two
+more joysticks/pads.
+
+turbografx.c
+------------
+
+The turbografx.c driver uses a very simple kernel/module command line::
+
+       turbografx.map=port,js1,js2,js3,js4,js5,js6,js7
+
+Where ``port`` is the number of the parport interface (eg. 0 for parport0).
+
+``jsX`` is the number of buttons the Multisystem joysticks connected to the
+interface ports 1-7 have. For a standard multisystem joystick, this is 1.
+
+Should you want to use more than one of these interfaces at once, you can
+use turbografx.map2 and turbografx.map3 as additional command line parameters
+for two more interfaces.
+
+PC parallel port pinout
+=======================
+
+::
+
+                 .----------------------------------------.
+   At the PC:     \ 13 12 11 10  9  8  7  6  5  4  3  2  1 /
+                   \  25 24 23 22 21 20 19 18 17 16 15 14 /
+                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+======  =======  =============
+   Pin  Name     Description
+======  =======  =============
+     1  /STROBE  Strobe
+   2-9  D0-D7    Data Bit 0-7
+    10  /ACK     Acknowledge
+    11  BUSY     Busy
+    12  PE       Paper End
+    13  SELIN    Select In
+    14  /AUTOFD  Autofeed
+    15  /ERROR   Error
+    16  /INIT    Initialize
+    17  /SEL     Select
+ 18-25  GND      Signal Ground
+======  =======  =============
+
+
+That's all, folks! Have fun!
diff --git a/Documentation/input/devices/ntrig.rst b/Documentation/input/devices/ntrig.rst
new file mode 100644 (file)
index 0000000..a6b22ce
--- /dev/null
@@ -0,0 +1,137 @@
+.. include:: <isonum.txt>
+
+=========================
+N-Trig touchscreen Driver
+=========================
+
+:Copyright: |copy| 2008-2010 Rafi Rubin <rafi@seas.upenn.edu>
+:Copyright: |copy| 2009-2010 Stephane Chatty
+
+This driver provides support for N-Trig pen and multi-touch sensors.  Single
+and multi-touch events are translated to the appropriate protocols for
+the hid and input systems.  Pen events are sufficiently hid compliant and
+are left to the hid core.  The driver also provides additional filtering
+and utility functions accessible with sysfs and module parameters.
+
+This driver has been reported to work properly with multiple N-Trig devices
+attached.
+
+
+Parameters
+----------
+
+Note: values set at load time are global and will apply to all applicable
+devices.  Adjusting parameters with sysfs will override the load time values,
+but only for that one device.
+
+The following parameters are used to configure filters to reduce noise:
+
++-----------------------+-----------------------------------------------------+
+|activate_slack                |number of fingers to ignore before processing events |
++-----------------------+-----------------------------------------------------+
+|activation_height,    |size threshold to activate immediately               |
+|activation_width      |                                                     |
++-----------------------+-----------------------------------------------------+
+|min_height,           |size threshold bellow which fingers are ignored      |
+|min_width             |both to decide activation and during activity        |
++-----------------------+-----------------------------------------------------+
+|deactivate_slack      |the number of "no contact" frames to ignore before   |
+|                      |propagating the end of activity events               |
++-----------------------+-----------------------------------------------------+
+
+When the last finger is removed from the device, it sends a number of empty
+frames.  By holding off on deactivation for a few frames we can tolerate false
+erroneous disconnects, where the sensor may mistakenly not detect a finger that
+is still present.  Thus deactivate_slack addresses problems where a users might
+see breaks in lines during drawing, or drop an object during a long drag.
+
+
+Additional sysfs items
+----------------------
+
+These nodes just provide easy access to the ranges reported by the device.
+
++-----------------------+-----------------------------------------------------+
+|sensor_logical_height, | the range for positions reported during activity    |
+|sensor_logical_width   |                                                     |
++-----------------------+-----------------------------------------------------+
+|sensor_physical_height,| internal ranges not used for normal events but      |
+|sensor_physical_width  | useful for tuning                                   |
++-----------------------+-----------------------------------------------------+
+
+All N-Trig devices with product id of 1 report events in the ranges of
+
+* X: 0-9600
+* Y: 0-7200
+
+However not all of these devices have the same physical dimensions.  Most
+seem to be 12" sensors (Dell Latitude XT and XT2 and the HP TX2), and
+at least one model (Dell Studio 17) has a 17" sensor.  The ratio of physical
+to logical sizes is used to adjust the size based filter parameters.
+
+
+Filtering
+---------
+
+With the release of the early multi-touch firmwares it became increasingly
+obvious that these sensors were prone to erroneous events.  Users reported
+seeing both inappropriately dropped contact and ghosts, contacts reported
+where no finger was actually touching the screen.
+
+Deactivation slack helps prevent dropped contact for single touch use, but does
+not address the problem of dropping one of more contacts while other contacts
+are still active.  Drops in the multi-touch context require additional
+processing and should be handled in tandem with tacking.
+
+As observed ghost contacts are similar to actual use of the sensor, but they
+seem to have different profiles.  Ghost activity typically shows up as small
+short lived touches.  As such, I assume that the longer the continuous stream
+of events the more likely those events are from a real contact, and that the
+larger the size of each contact the more likely it is real.  Balancing the
+goals of preventing ghosts and accepting real events quickly (to minimize
+user observable latency), the filter accumulates confidence for incoming
+events until it hits thresholds and begins propagating.  In the interest in
+minimizing stored state as well as the cost of operations to make a decision,
+I've kept that decision simple.
+
+Time is measured in terms of the number of fingers reported, not frames since
+the probability of multiple simultaneous ghosts is expected to drop off
+dramatically with increasing numbers.  Rather than accumulate weight as a
+function of size, I just use it as a binary threshold.  A sufficiently large
+contact immediately overrides the waiting period and leads to activation.
+
+Setting the activation size thresholds to large values will result in deciding
+primarily on activation slack.  If you see longer lived ghosts, turning up the
+activation slack while reducing the size thresholds may suffice to eliminate
+the ghosts while keeping the screen quite responsive to firm taps.
+
+Contacts continue to be filtered with min_height and min_width even after
+the initial activation filter is satisfied.  The intent is to provide
+a mechanism for filtering out ghosts in the form of an extra finger while
+you actually are using the screen.  In practice this sort of ghost has
+been far less problematic or relatively rare and I've left the defaults
+set to 0 for both parameters, effectively turning off that filter.
+
+I don't know what the optimal values are for these filters.  If the defaults
+don't work for you, please play with the parameters.  If you do find other
+values more comfortable, I would appreciate feedback.
+
+The calibration of these devices does drift over time.  If ghosts or contact
+dropping worsen and interfere with the normal usage of your device, try
+recalibrating it.
+
+
+Calibration
+-----------
+
+The N-Trig windows tools provide calibration and testing routines.  Also an
+unofficial unsupported set of user space tools including a calibrator is
+available at:
+http://code.launchpad.net/~rafi-seas/+junk/ntrig_calib
+
+
+Tracking
+--------
+
+As of yet, all tested N-Trig firmwares do not track fingers.  When multiple
+contacts are active they seem to be sorted primarily by Y position.
diff --git a/Documentation/input/devices/rotary-encoder.rst b/Documentation/input/devices/rotary-encoder.rst
new file mode 100644 (file)
index 0000000..b07b20a
--- /dev/null
@@ -0,0 +1,131 @@
+============================================================
+rotary-encoder - a generic driver for GPIO connected devices
+============================================================
+
+:Author: Daniel Mack <daniel@caiaq.de>, Feb 2009
+
+Function
+--------
+
+Rotary encoders are devices which are connected to the CPU or other
+peripherals with two wires. The outputs are phase-shifted by 90 degrees
+and by triggering on falling and rising edges, the turn direction can
+be determined.
+
+Some encoders have both outputs low in stable states, others also have
+a stable state with both outputs high (half-period mode) and some have
+a stable state in all steps (quarter-period mode).
+
+The phase diagram of these two outputs look like this::
+
+                  _____       _____       _____
+                 |     |     |     |     |     |
+  Channel A  ____|     |_____|     |_____|     |____
+
+                 :  :  :  :  :  :  :  :  :  :  :  :
+            __       _____       _____       _____
+              |     |     |     |     |     |     |
+  Channel B   |_____|     |_____|     |_____|     |__
+
+                 :  :  :  :  :  :  :  :  :  :  :  :
+  Event          a  b  c  d  a  b  c  d  a  b  c  d
+
+                |<-------->|
+                 one step
+
+                |<-->|
+                 one step (half-period mode)
+
+                |<>|
+                 one step (quarter-period mode)
+
+For more information, please see
+       https://en.wikipedia.org/wiki/Rotary_encoder
+
+
+Events / state machine
+----------------------
+
+In half-period mode, state a) and c) above are used to determine the
+rotational direction based on the last stable state. Events are reported in
+states b) and d) given that the new stable state is different from the last
+(i.e. the rotation was not reversed half-way).
+
+Otherwise, the following apply:
+
+a) Rising edge on channel A, channel B in low state
+       This state is used to recognize a clockwise turn
+
+b) Rising edge on channel B, channel A in high state
+       When entering this state, the encoder is put into 'armed' state,
+       meaning that there it has seen half the way of a one-step transition.
+
+c) Falling edge on channel A, channel B in high state
+       This state is used to recognize a counter-clockwise turn
+
+d) Falling edge on channel B, channel A in low state
+       Parking position. If the encoder enters this state, a full transition
+       should have happened, unless it flipped back on half the way. The
+       'armed' state tells us about that.
+
+Platform requirements
+---------------------
+
+As there is no hardware dependent call in this driver, the platform it is
+used with must support gpiolib. Another requirement is that IRQs must be
+able to fire on both edges.
+
+
+Board integration
+-----------------
+
+To use this driver in your system, register a platform_device with the
+name 'rotary-encoder' and associate the IRQs and some specific platform
+data with it. Because the driver uses generic device properties, this can
+be done either via device tree, ACPI, or using static board files, like in
+example below:
+
+::
+
+       /* board support file example */
+
+       #include <linux/input.h>
+       #include <linux/gpio/machine.h>
+       #include <linux/property.h>
+
+       #define GPIO_ROTARY_A 1
+       #define GPIO_ROTARY_B 2
+
+       static struct gpiod_lookup_table rotary_encoder_gpios = {
+               .dev_id = "rotary-encoder.0",
+               .table = {
+                       GPIO_LOOKUP_IDX("gpio-0",
+                                       GPIO_ROTARY_A, NULL, 0, GPIO_ACTIVE_LOW),
+                       GPIO_LOOKUP_IDX("gpio-0",
+                                       GPIO_ROTARY_B, NULL, 1, GPIO_ACTIVE_HIGH),
+                       { },
+               },
+       };
+
+       static const struct property_entry rotary_encoder_properties[] __initconst = {
+               PROPERTY_ENTRY_INTEGER("rotary-encoder,steps-per-period", u32, 24),
+               PROPERTY_ENTRY_INTEGER("linux,axis",                      u32, ABS_X),
+               PROPERTY_ENTRY_INTEGER("rotary-encoder,relative_axis",    u32, 0),
+               { },
+       };
+
+       static struct platform_device rotary_encoder_device = {
+               .name           = "rotary-encoder",
+               .id             = 0,
+       };
+
+       ...
+
+       gpiod_add_lookup_table(&rotary_encoder_gpios);
+       device_add_properties(&rotary_encoder_device, rotary_encoder_properties);
+       platform_device_register(&rotary_encoder_device);
+
+       ...
+
+Please consult device tree binding documentation to see all properties
+supported by the driver.
diff --git a/Documentation/input/devices/sentelic.rst b/Documentation/input/devices/sentelic.rst
new file mode 100644 (file)
index 0000000..d7ad603
--- /dev/null
@@ -0,0 +1,901 @@
+.. include:: <isonum.txt>
+
+=================
+Sentelic Touchpad
+=================
+
+
+:Copyright: |copy| 2002-2011 Sentelic Corporation.
+
+:Last update: Dec-07-2011
+
+Finger Sensing Pad Intellimouse Mode (scrolling wheel, 4th and 5th buttons)
+============================================================================
+
+A) MSID 4: Scrolling wheel mode plus Forward page(4th button) and Backward
+   page (5th button)
+
+1. Set sample rate to 200;
+2. Set sample rate to 200;
+3. Set sample rate to 80;
+4. Issuing the "Get device ID" command (0xF2) and waits for the response;
+5. FSP will respond 0x04.
+
+::
+
+    Packet 1
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |Y|X|y|x|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 | | |B|F|W|W|W|W|
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7 => Y overflow
+           Bit6 => X overflow
+           Bit5 => Y sign bit
+           Bit4 => X sign bit
+           Bit3 => 1
+           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X Movement(9-bit 2's complement integers)
+    Byte 3: Y Movement(9-bit 2's complement integers)
+    Byte 4: Bit3~Bit0 => the scrolling wheel's movement since the last data report.
+                       valid values, -8 ~ +7
+           Bit4 => 1 = 4th mouse button is pressed, Forward one page.
+                   0 = 4th mouse button is not pressed.
+           Bit5 => 1 = 5th mouse button is pressed, Backward one page.
+                   0 = 5th mouse button is not pressed.
+
+B) MSID 6: Horizontal and Vertical scrolling
+
+- Set bit 1 in register 0x40 to 1
+
+FSP replaces scrolling wheel's movement as 4 bits to show horizontal and
+vertical scrolling.
+
+::
+
+    Packet 1
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |Y|X|y|x|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 | | |B|F|r|l|u|d|
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7 => Y overflow
+           Bit6 => X overflow
+           Bit5 => Y sign bit
+           Bit4 => X sign bit
+           Bit3 => 1
+           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X Movement(9-bit 2's complement integers)
+    Byte 3: Y Movement(9-bit 2's complement integers)
+    Byte 4: Bit0 => the Vertical scrolling movement downward.
+           Bit1 => the Vertical scrolling movement upward.
+           Bit2 => the Horizontal scrolling movement leftward.
+           Bit3 => the Horizontal scrolling movement rightward.
+           Bit4 => 1 = 4th mouse button is pressed, Forward one page.
+                   0 = 4th mouse button is not pressed.
+           Bit5 => 1 = 5th mouse button is pressed, Backward one page.
+                   0 = 5th mouse button is not pressed.
+
+C) MSID 7
+
+FSP uses 2 packets (8 Bytes) to represent Absolute Position.
+so we have PACKET NUMBER to identify packets.
+
+  If PACKET NUMBER is 0, the packet is Packet 1.
+  If PACKET NUMBER is 1, the packet is Packet 2.
+  Please count this number in program.
+
+MSID6 special packet will be enable at the same time when enable MSID 7.
+
+Absolute position for STL3886-G0
+================================
+
+1. Set bit 2 or 3 in register 0x40 to 1
+2. Set bit 6 in register 0x40 to 1
+
+::
+
+    Packet 1 (ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|1|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|d|u|X|X|Y|Y|
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+                   => 01, Absolute coordination packet
+                   => 10, Notify packet
+           Bit5 => valid bit
+           Bit4 => 1
+           Bit3 => 1
+           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+           Bit3~Bit2 => X coordinate (ypos[1:0])
+           Bit4 => scroll up
+           Bit5 => scroll down
+           Bit6 => scroll left
+           Bit7 => scroll right
+
+    Notify Packet for G0
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |1|0|0|1|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |M|M|M|M|M|M|M|M|  4 |0|0|0|0|0|0|0|0|
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+                   => 01, Absolute coordination packet
+                   => 10, Notify packet
+           Bit5 => 0
+           Bit4 => 1
+           Bit3 => 1
+           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: Message Type => 0x5A (Enable/Disable status packet)
+           Mode Type => 0xA5 (Normal/Icon mode status)
+    Byte 3: Message Type => 0x00 (Disabled)
+                       => 0x01 (Enabled)
+           Mode Type    => 0x00 (Normal)
+                       => 0x01 (Icon)
+    Byte 4: Bit7~Bit0 => Don't Care
+
+Absolute position for STL3888-Ax
+================================
+
+::
+
+    Packet 1 (ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|A|1|L|0|1|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |x|x|y|y|X|X|Y|Y|
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+                   => 01, Absolute coordination packet
+                   => 10, Notify packet
+                   => 11, Normal data packet with on-pad click
+           Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
+                   When both fingers are up, the last two reports have zero valid
+                   bit.
+           Bit4 => arc
+           Bit3 => 1
+           Bit2 => Left Button, 1 is pressed, 0 is released.
+           Bit1 => 0
+           Bit0 => 1
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+           Bit3~Bit2 => X coordinate (ypos[1:0])
+           Bit5~Bit4 => y1_g
+           Bit7~Bit6 => x1_g
+
+    Packet 2 (ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|A|1|R|1|0|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |x|x|y|y|X|X|Y|Y|
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+                   => 01, Absolute coordinates packet
+                   => 10, Notify packet
+                   => 11, Normal data packet with on-pad click
+           Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
+                   When both fingers are up, the last two reports have zero valid
+                   bit.
+           Bit4 => arc
+           Bit3 => 1
+           Bit2 => Right Button, 1 is pressed, 0 is released.
+           Bit1 => 1
+           Bit0 => 0
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+           Bit3~Bit2 => X coordinate (ypos[1:0])
+           Bit5~Bit4 => y2_g
+           Bit7~Bit6 => x2_g
+
+    Notify Packet for STL3888-Ax
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |1|0|1|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|d|u|0|0|0|0|
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+                   => 01, Absolute coordinates packet
+                   => 10, Notify packet
+                   => 11, Normal data packet with on-pad click
+           Bit5 => 1
+           Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1):
+                   0: left button is generated by the on-pad command
+                   1: left button is generated by the external button
+           Bit3 => 1
+           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode)
+    Byte 3: Bit7~Bit6 => Don't care
+           Bit5~Bit4 => Number of fingers
+           Bit3~Bit1 => Reserved
+           Bit0 => 1: enter gesture mode; 0: leaving gesture mode
+    Byte 4: Bit7 => scroll right button
+           Bit6 => scroll left button
+           Bit5 => scroll down button
+           Bit4 => scroll up button
+               * Note that if gesture and additional button (Bit4~Bit7)
+               happen at the same time, the button information will not
+               be sent.
+           Bit3~Bit0 => Reserved
+
+Sample sequence of Multi-finger, Multi-coordinate mode:
+
+       notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1,
+       abs pkt 2, ..., notify packet (valid bit == 0)
+
+Absolute position for STL3888-B0
+================================
+
+::
+
+    Packet 1(ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|F|1|0|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|u|d|X|X|Y|Y|
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+                   => 01, Absolute coordinates packet
+                   => 10, Notify packet
+                   => 11, Normal data packet with on-pad click
+           Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
+                   When both fingers are up, the last two reports have zero valid
+                   bit.
+           Bit4 => finger up/down information. 1: finger down, 0: finger up.
+           Bit3 => 1
+           Bit2 => finger index, 0 is the first finger, 1 is the second finger.
+           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+           Bit3~Bit2 => X coordinate (ypos[1:0])
+           Bit4 => scroll down button
+           Bit5 => scroll up button
+           Bit6 => scroll left button
+           Bit7 => scroll right button
+
+    Packet 2 (ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|F|1|1|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|u|d|X|X|Y|Y|
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+                   => 01, Absolute coordination packet
+                   => 10, Notify packet
+                   => 11, Normal data packet with on-pad click
+           Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
+                   When both fingers are up, the last two reports have zero valid
+                   bit.
+           Bit4 => finger up/down information. 1: finger down, 0: finger up.
+           Bit3 => 1
+           Bit2 => finger index, 0 is the first finger, 1 is the second finger.
+           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+           Bit3~Bit2 => X coordinate (ypos[1:0])
+           Bit4 => scroll down button
+           Bit5 => scroll up button
+           Bit6 => scroll left button
+           Bit7 => scroll right button
+
+Notify Packet for STL3888-B0::
+
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |1|0|1|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|u|d|0|0|0|0|
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+                   => 01, Absolute coordination packet
+                   => 10, Notify packet
+                   => 11, Normal data packet with on-pad click
+           Bit5 => 1
+           Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1):
+                   0: left button is generated by the on-pad command
+                   1: left button is generated by the external button
+           Bit3 => 1
+           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode)
+    Byte 3: Bit7~Bit6 => Don't care
+           Bit5~Bit4 => Number of fingers
+           Bit3~Bit1 => Reserved
+           Bit0 => 1: enter gesture mode; 0: leaving gesture mode
+    Byte 4: Bit7 => scroll right button
+           Bit6 => scroll left button
+           Bit5 => scroll up button
+           Bit4 => scroll down button
+               * Note that if gesture and additional button(Bit4~Bit7)
+               happen at the same time, the button information will not
+               be sent.
+           Bit3~Bit0 => Reserved
+
+Sample sequence of Multi-finger, Multi-coordinate mode:
+
+       notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1,
+       abs pkt 2, ..., notify packet (valid bit == 0)
+
+Absolute position for STL3888-Cx and STL3888-Dx
+===============================================
+
+::
+
+    Single Finger, Absolute Coordinate Mode (SFAC)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|0|P|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|B|F|X|X|Y|Y|
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+                   => 01, Absolute coordinates packet
+                   => 10, Notify packet
+           Bit5 => Coordinate mode(always 0 in SFAC mode):
+                   0: single-finger absolute coordinates (SFAC) mode
+                   1: multi-finger, multiple coordinates (MFMC) mode
+           Bit4 => 0: The LEFT button is generated by on-pad command (OPC)
+                   1: The LEFT button is generated by external button
+                   Default is 1 even if the LEFT button is not pressed.
+           Bit3 => Always 1, as specified by PS/2 protocol.
+           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+           Bit3~Bit2 => X coordinate (ypos[1:0])
+           Bit4 => 4th mouse button(forward one page)
+           Bit5 => 5th mouse button(backward one page)
+           Bit6 => scroll left button
+           Bit7 => scroll right button
+
+    Multi Finger, Multiple Coordinates Mode (MFMC):
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|1|P|1|F|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|B|F|X|X|Y|Y|
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+                   => 01, Absolute coordination packet
+                   => 10, Notify packet
+           Bit5 => Coordinate mode (always 1 in MFMC mode):
+                   0: single-finger absolute coordinates (SFAC) mode
+                   1: multi-finger, multiple coordinates (MFMC) mode
+           Bit4 => 0: The LEFT button is generated by on-pad command (OPC)
+                   1: The LEFT button is generated by external button
+                   Default is 1 even if the LEFT button is not pressed.
+           Bit3 => Always 1, as specified by PS/2 protocol.
+           Bit2 => Finger index, 0 is the first finger, 1 is the second finger.
+                   If bit 1 and 0 are all 1 and bit 4 is 0, the middle external
+                   button is pressed.
+           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+           Bit3~Bit2 => X coordinate (ypos[1:0])
+           Bit4 => 4th mouse button(forward one page)
+           Bit5 => 5th mouse button(backward one page)
+           Bit6 => scroll left button
+           Bit7 => scroll right button
+
+When one of the two fingers is up, the device will output four consecutive
+MFMC#0 report packets with zero X and Y to represent 1st finger is up or
+four consecutive MFMC#1 report packets with zero X and Y to represent that
+the 2nd finger is up.  On the other hand, if both fingers are up, the device
+will output four consecutive single-finger, absolute coordinate(SFAC) packets
+with zero X and Y.
+
+Notify Packet for STL3888-Cx/Dx::
+
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |1|0|0|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|u|d|0|0|0|0|
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+                   => 01, Absolute coordinates packet
+                   => 10, Notify packet
+           Bit5 => Always 0
+           Bit4 => 0: The LEFT button is generated by on-pad command(OPC)
+                   1: The LEFT button is generated by external button
+                   Default is 1 even if the LEFT button is not pressed.
+           Bit3 => 1
+           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: Message type:
+           0xba => gesture information
+           0xc0 => one finger hold-rotating gesture
+    Byte 3: The first parameter for the received message:
+           0xba => gesture ID (refer to the 'Gesture ID' section)
+           0xc0 => region ID
+    Byte 4: The second parameter for the received message:
+           0xba => N/A
+           0xc0 => finger up/down information
+
+Sample sequence of Multi-finger, Multi-coordinates mode:
+
+       notify packet (valid bit == 1), MFMC packet 1 (byte 1, bit 2 == 0),
+       MFMC packet 2 (byte 1, bit 2 == 1), MFMC packet 1, MFMC packet 2,
+       ..., notify packet (valid bit == 0)
+
+       That is, when the device is in MFMC mode, the host will receive
+       interleaved absolute coordinate packets for each finger.
+
+FSP Enable/Disable packet
+=========================
+
+::
+
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |Y|X|0|0|1|M|R|L|  2  |0|1|0|1|1|0|1|E|  3 | | | | | | | | |  4 | | | | | | | | |
+         |---------------|     |---------------|    |---------------|    |---------------|
+
+    FSP will send out enable/disable packet when FSP receive PS/2 enable/disable
+    command. Host will receive the packet which Middle, Right, Left button will
+    be set. The packet only use byte 0 and byte 1 as a pattern of original packet.
+    Ignore the other bytes of the packet.
+
+    Byte 1: Bit7 => 0, Y overflow
+           Bit6 => 0, X overflow
+           Bit5 => 0, Y sign bit
+           Bit4 => 0, X sign bit
+           Bit3 => 1
+           Bit2 => 1, Middle Button
+           Bit1 => 1, Right Button
+           Bit0 => 1, Left Button
+    Byte 2: Bit7~1 => (0101101b)
+           Bit0 => 1 = Enable
+                   0 = Disable
+    Byte 3: Don't care
+    Byte 4: Don't care (MOUSE ID 3, 4)
+    Byte 5~8: Don't care (Absolute packet)
+
+PS/2 Command Set
+================
+
+FSP supports basic PS/2 commanding set and modes, refer to following URL for
+details about PS/2 commands:
+
+http://www.computer-engineering.org/ps2mouse/
+
+Programming Sequence for Determining Packet Parsing Flow
+========================================================
+
+1. Identify FSP by reading device ID(0x00) and version(0x01) register
+
+2. For FSP version < STL3888 Cx, determine number of buttons by reading
+   the 'test mode status' (0x20) register::
+
+       buttons = reg[0x20] & 0x30
+
+       if buttons == 0x30 or buttons == 0x20:
+               # two/four buttons
+               Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse'
+               section A for packet parsing detail(ignore byte 4, bit ~ 7)
+       elif buttons == 0x10:
+               # 6 buttons
+               Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse'
+               section B for packet parsing detail
+       elif buttons == 0x00:
+               # 6 buttons
+               Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse'
+               section A for packet parsing detail
+
+3. For FSP version >= STL3888 Cx:
+       Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse'
+       section A for packet parsing detail (ignore byte 4, bit ~ 7)
+
+Programming Sequence for Register Reading/Writing
+=================================================
+
+Register inversion requirement:
+
+Following values needed to be inverted(the '~' operator in C) before being
+sent to FSP::
+
+       0xe8, 0xe9, 0xee, 0xf2, 0xf3 and 0xff.
+
+Register swapping requirement:
+
+Following values needed to have their higher 4 bits and lower 4 bits being
+swapped before being sent to FSP::
+
+       10, 20, 40, 60, 80, 100 and 200.
+
+Register reading sequence:
+
+       1. send 0xf3 PS/2 command to FSP;
+
+       2. send 0x66 PS/2 command to FSP;
+
+       3. send 0x88 PS/2 command to FSP;
+
+       4. send 0xf3 PS/2 command to FSP;
+
+       5. if the register address being to read is not required to be
+       inverted(refer to the 'Register inversion requirement' section),
+       goto step 6
+
+         a. send 0x68 PS/2 command to FSP;
+
+         b. send the inverted register address to FSP and goto step 8;
+
+       6. if the register address being to read is not required to be
+       swapped(refer to the 'Register swapping requirement' section),
+       goto step 7
+
+         a. send 0xcc PS/2 command to FSP;
+
+         b. send the swapped register address to FSP and goto step 8;
+
+       7. send 0x66 PS/2 command to FSP;
+
+         a. send the original register address to FSP and goto step 8;
+
+       8. send 0xe9(status request) PS/2 command to FSP;
+
+       9. the 4th byte of the response read from FSP should be the
+       requested register value(?? indicates don't care byte)::
+
+               host: 0xe9
+               3888: 0xfa (??) (??) (val)
+
+       * Note that since the Cx release, the hardware will return 1's
+         complement of the register value at the 3rd byte of status request
+         result::
+
+               host: 0xe9
+               3888: 0xfa (??) (~val) (val)
+
+Register writing sequence:
+
+       1. send 0xf3 PS/2 command to FSP;
+
+       2. if the register address being to write is not required to be
+       inverted(refer to the 'Register inversion requirement' section),
+       goto step 3
+
+         a. send 0x74 PS/2 command to FSP;
+
+         b. send the inverted register address to FSP and goto step 5;
+
+       3. if the register address being to write is not required to be
+       swapped(refer to the 'Register swapping requirement' section),
+       goto step 4
+
+         a. send 0x77 PS/2 command to FSP;
+
+         b. send the swapped register address to FSP and goto step 5;
+
+       4. send 0x55 PS/2 command to FSP;
+
+         a. send the register address to FSP and goto step 5;
+
+       5. send 0xf3 PS/2 command to FSP;
+
+       6. if the register value being to write is not required to be
+       inverted(refer to the 'Register inversion requirement' section),
+       goto step 7
+
+         a. send 0x47 PS/2 command to FSP;
+
+         b. send the inverted register value to FSP and goto step 9;
+
+       7. if the register value being to write is not required to be
+       swapped(refer to the 'Register swapping requirement' section),
+       goto step 8
+
+         a. send 0x44 PS/2 command to FSP;
+
+         b. send the swapped register value to FSP and goto step 9;
+
+       8. send 0x33 PS/2 command to FSP;
+
+         a. send the register value to FSP;
+
+       9. the register writing sequence is completed.
+
+       * Since the Cx release, the hardware will return 1's
+         complement of the register value at the 3rd byte of status request
+         result. Host can optionally send another 0xe9 (status request) PS/2
+         command to FSP at the end of register writing to verify that the
+         register writing operation is successful (?? indicates don't care
+         byte)::
+
+               host: 0xe9
+               3888: 0xfa (??) (~val) (val)
+
+Programming Sequence for Page Register Reading/Writing
+======================================================
+
+In order to overcome the limitation of maximum number of registers
+supported, the hardware separates register into different groups called
+'pages.' Each page is able to include up to 255 registers.
+
+The default page after power up is 0x82; therefore, if one has to get
+access to register 0x8301, one has to use following sequence to switch
+to page 0x83, then start reading/writing from/to offset 0x01 by using
+the register read/write sequence described in previous section.
+
+Page register reading sequence:
+
+       1. send 0xf3 PS/2 command to FSP;
+
+       2. send 0x66 PS/2 command to FSP;
+
+       3. send 0x88 PS/2 command to FSP;
+
+       4. send 0xf3 PS/2 command to FSP;
+
+       5. send 0x83 PS/2 command to FSP;
+
+       6. send 0x88 PS/2 command to FSP;
+
+       7. send 0xe9(status request) PS/2 command to FSP;
+
+       8. the response read from FSP should be the requested page value.
+
+
+Page register writing sequence:
+
+       1. send 0xf3 PS/2 command to FSP;
+
+       2. send 0x38 PS/2 command to FSP;
+
+       3. send 0x88 PS/2 command to FSP;
+
+       4. send 0xf3 PS/2 command to FSP;
+
+       5. if the page address being written is not required to be
+       inverted(refer to the 'Register inversion requirement' section),
+       goto step 6
+
+         a. send 0x47 PS/2 command to FSP;
+
+         b. send the inverted page address to FSP and goto step 9;
+
+       6. if the page address being written is not required to be
+       swapped(refer to the 'Register swapping requirement' section),
+       goto step 7
+
+         a. send 0x44 PS/2 command to FSP;
+
+         b. send the swapped page address to FSP and goto step 9;
+
+       7. send 0x33 PS/2 command to FSP;
+
+       8. send the page address to FSP;
+
+       9. the page register writing sequence is completed.
+
+Gesture ID
+==========
+
+Unlike other devices which sends multiple fingers' coordinates to host,
+FSP processes multiple fingers' coordinates internally and convert them
+into a 8 bits integer, namely 'Gesture ID.'  Following is a list of
+supported gesture IDs:
+
+       ======= ==================================
+       ID      Description
+       ======= ==================================
+       0x86    2 finger straight up
+       0x82    2 finger straight down
+       0x80    2 finger straight right
+       0x84    2 finger straight left
+       0x8f    2 finger zoom in
+       0x8b    2 finger zoom out
+       0xc0    2 finger curve, counter clockwise
+       0xc4    2 finger curve, clockwise
+       0x2e    3 finger straight up
+       0x2a    3 finger straight down
+       0x28    3 finger straight right
+       0x2c    3 finger straight left
+       0x38    palm
+       ======= ==================================
+
+Register Listing
+================
+
+Registers are represented in 16 bits values. The higher 8 bits represent
+the page address and the lower 8 bits represent the relative offset within
+that particular page.  Refer to the 'Programming Sequence for Page Register
+Reading/Writing' section for instructions on how to change current page
+address::
+
+ offset        width           default r/w     name
+ 0x8200        bit7~bit0       0x01    RO      device ID
+
+ 0x8201        bit7~bit0               RW      version ID
+                                       0xc1: STL3888 Ax
+                                       0xd0 ~ 0xd2: STL3888 Bx
+                                       0xe0 ~ 0xe1: STL3888 Cx
+                                       0xe2 ~ 0xe3: STL3888 Dx
+
+ 0x8202        bit7~bit0       0x01    RO      vendor ID
+
+ 0x8203        bit7~bit0       0x01    RO      product ID
+
+ 0x8204        bit3~bit0       0x01    RW      revision ID
+
+ 0x820b                                        test mode status 1
+       bit3            1       RO      0: rotate 180 degree
+                                       1: no rotation
+                                       *only supported by H/W prior to Cx
+
+ 0x820f                                        register file page control
+       bit2            0       RW      1: rotate 180 degree
+                                       0: no rotation
+                                       *supported since Cx
+
+       bit0            0       RW      1 to enable page 1 register files
+                                       *only supported by H/W prior to Cx
+
+ 0x8210                                RW      system control 1
+       bit0            1       RW      Reserved, must be 1
+       bit1            0       RW      Reserved, must be 0
+       bit4            0       RW      Reserved, must be 0
+       bit5            1       RW      register clock gating enable
+                                       0: read only, 1: read/write enable
+       (Note that following registers does not require clock gating being
+       enabled prior to write: 05 06 07 08 09 0c 0f 10 11 12 16 17 18 23 2e
+       40 41 42 43.  In addition to that, this bit must be 1 when gesture
+       mode is enabled)
+
+ 0x8220                                        test mode status
+       bit5~bit4               RO      number of buttons
+                                       11 => 2, lbtn/rbtn
+                                       10 => 4, lbtn/rbtn/scru/scrd
+                                       01 => 6, lbtn/rbtn/scru/scrd/scrl/scrr
+                                       00 => 6, lbtn/rbtn/scru/scrd/fbtn/bbtn
+                                       *only supported by H/W prior to Cx
+
+ 0x8231                                RW      on-pad command detection
+       bit7            0       RW      on-pad command left button down tag
+                                       enable
+                                       0: disable, 1: enable
+                                       *only supported by H/W prior to Cx
+
+ 0x8234                                RW      on-pad command control 5
+       bit4~bit0       0x05    RW      XLO in 0s/4/1, so 03h = 0010.1b = 2.5
+       (Note that position unit is in 0.5 scanline)
+                                       *only supported by H/W prior to Cx
+
+       bit7            0       RW      on-pad tap zone enable
+                                       0: disable, 1: enable
+                                       *only supported by H/W prior to Cx
+
+ 0x8235                                RW      on-pad command control 6
+       bit4~bit0       0x1d    RW      XHI in 0s/4/1, so 19h = 1100.1b = 12.5
+       (Note that position unit is in 0.5 scanline)
+                                       *only supported by H/W prior to Cx
+
+ 0x8236                                RW      on-pad command control 7
+       bit4~bit0       0x04    RW      YLO in 0s/4/1, so 03h = 0010.1b = 2.5
+       (Note that position unit is in 0.5 scanline)
+                                       *only supported by H/W prior to Cx
+
+ 0x8237                                RW      on-pad command control 8
+       bit4~bit0       0x13    RW      YHI in 0s/4/1, so 11h = 1000.1b = 8.5
+       (Note that position unit is in 0.5 scanline)
+                                       *only supported by H/W prior to Cx
+
+ 0x8240                                RW      system control 5
+       bit1            0       RW      FSP Intellimouse mode enable
+                                       0: disable, 1: enable
+                                       *only supported by H/W prior to Cx
+
+       bit2            0       RW      movement + abs. coordinate mode enable
+                                       0: disable, 1: enable
+       (Note that this function has the functionality of bit 1 even when
+       bit 1 is not set. However, the format is different from that of bit 1.
+       In addition, when bit 1 and bit 2 are set at the same time, bit 2 will
+       override bit 1.)
+                                       *only supported by H/W prior to Cx
+
+       bit3            0       RW      abs. coordinate only mode enable
+                                       0: disable, 1: enable
+       (Note that this function has the functionality of bit 1 even when
+       bit 1 is not set. However, the format is different from that of bit 1.
+       In addition, when bit 1, bit 2 and bit 3 are set at the same time,
+       bit 3 will override bit 1 and 2.)
+                                       *only supported by H/W prior to Cx
+
+       bit5            0       RW      auto switch enable
+                                       0: disable, 1: enable
+                                       *only supported by H/W prior to Cx
+
+       bit6            0       RW      G0 abs. + notify packet format enable
+                                       0: disable, 1: enable
+       (Note that the absolute/relative coordinate output still depends on
+       bit 2 and 3.  That is, if any of those bit is 1, host will receive
+       absolute coordinates; otherwise, host only receives packets with
+       relative coordinate.)
+                                       *only supported by H/W prior to Cx
+
+       bit7            0       RW      EN_PS2_F2: PS/2 gesture mode 2nd
+                                       finger packet enable
+                                       0: disable, 1: enable
+                                       *only supported by H/W prior to Cx
+
+ 0x8243                                RW      on-pad control
+       bit0            0       RW      on-pad control enable
+                                       0: disable, 1: enable
+       (Note that if this bit is cleared, bit 3/5 will be ineffective)
+                                       *only supported by H/W prior to Cx
+
+       bit3            0       RW      on-pad fix vertical scrolling enable
+                                       0: disable, 1: enable
+                                       *only supported by H/W prior to Cx
+
+       bit5            0       RW      on-pad fix horizontal scrolling enable
+                                       0: disable, 1: enable
+                                       *only supported by H/W prior to Cx
+
+ 0x8290                                RW      software control register 1
+       bit0            0       RW      absolute coordination mode
+                                       0: disable, 1: enable
+                                       *supported since Cx
+
+       bit1            0       RW      gesture ID output
+                                       0: disable, 1: enable
+                                       *supported since Cx
+
+       bit2            0       RW      two fingers' coordinates output
+                                       0: disable, 1: enable
+                                       *supported since Cx
+
+       bit3            0       RW      finger up one packet output
+                                       0: disable, 1: enable
+                                       *supported since Cx
+
+       bit4            0       RW      absolute coordination continuous mode
+                                       0: disable, 1: enable
+                                       *supported since Cx
+
+       bit6~bit5       00      RW      gesture group selection
+                                       00: basic
+                                       01: suite
+                                       10: suite pro
+                                       11: advanced
+                                       *supported since Cx
+
+       bit7            0       RW      Bx packet output compatible mode
+                                       0: disable, 1: enable
+                                       *supported since Cx
+                                       *supported since Cx
+
+
+ 0x833d                                RW      on-pad command control 1
+       bit7            1       RW      on-pad command detection enable
+                                       0: disable, 1: enable
+                                       *supported since Cx
+
+ 0x833e                                RW      on-pad command detection
+       bit7            0       RW      on-pad command left button down tag
+                                       enable. Works only in H/W based PS/2
+                                       data packet mode.
+                                       0: disable, 1: enable
+                                       *supported since Cx
diff --git a/Documentation/input/devices/walkera0701.rst b/Documentation/input/devices/walkera0701.rst
new file mode 100644 (file)
index 0000000..2adda99
--- /dev/null
@@ -0,0 +1,128 @@
+===========================
+Walkera WK-0701 transmitter
+===========================
+
+Walkera WK-0701 transmitter is supplied with a ready to fly Walkera
+helicopters such as HM36, HM37, HM60. The walkera0701 module enables to use
+this transmitter as joystick
+
+Devel homepage and download:
+http://zub.fei.tuke.sk/walkera-wk0701/
+
+or use cogito:
+cg-clone http://zub.fei.tuke.sk/GIT/walkera0701-joystick
+
+
+Connecting to PC
+================
+
+At back side of transmitter S-video connector can be found. Modulation
+pulses from processor to HF part can be found at pin 2 of this connector,
+pin 3 is GND. Between pin 3 and CPU 5k6 resistor can be found. To get
+modulation pulses to PC, signal pulses must be amplified.
+
+Cable: (walkera TX to parport)
+
+Walkera WK-0701 TX S-VIDEO connector::
+
+ (back side of TX)
+     __   __              S-video:                                  canon25
+    /  |_|  \             pin 2 (signal)              NPN           parport
+   / O 4 3 O \            pin 3 (GND)        LED        ________________  10 ACK
+  ( O 2   1 O )                                         | C
+   \   ___   /      2 ________________________|\|_____|/
+    | [___] |                                 |/|   B |\
+     -------        3 __________________________________|________________ 25 GND
+                                                          E
+
+I use green LED and BC109 NPN transistor.
+
+Software
+========
+
+Build kernel with walkera0701 module. Module walkera0701 need exclusive
+access to parport, modules like lp must be unloaded before loading
+walkera0701 module, check dmesg for error messages. Connect TX to PC by
+cable and run jstest /dev/input/js0 to see values from TX. If no value can
+be changed by TX "joystick", check output from /proc/interrupts. Value for
+(usually irq7) parport must increase if TX is on.
+
+
+
+Technical details
+=================
+
+Driver use interrupt from parport ACK input bit to measure pulse length
+using hrtimers.
+
+Frame format:
+Based on walkera WK-0701 PCM Format description by Shaul Eizikovich.
+(downloaded from http://www.smartpropoplus.com/Docs/Walkera_Wk-0701_PCM.pdf)
+
+Signal pulses
+-------------
+
+::
+
+                     (ANALOG)
+      SYNC      BIN   OCT
+    +---------+      +------+
+    |         |      |      |
+  --+         +------+      +---
+
+Frame
+-----
+
+::
+
+ SYNC , BIN1, OCT1, BIN2, OCT2 ... BIN24, OCT24, BIN25, next frame SYNC ..
+
+pulse length
+------------
+
+::
+
+   Binary values:              Analog octal values:
+
+   288 uS Binary 0             318 uS       000
+   438 uS Binary 1             398 uS       001
+                               478 uS       010
+                               558 uS       011
+                               638 uS       100
+  1306 uS SYNC                 718 uS       101
+                               798 uS       110
+                               878 uS       111
+
+24 bin+oct values + 1 bin value = 24*4+1 bits  = 97 bits
+
+(Warning, pulses on ACK are inverted by transistor, irq is raised up on sync
+to bin change or octal value to bin change).
+
+Binary data representations
+---------------------------
+
+One binary and octal value can be grouped to nibble. 24 nibbles + one binary
+values can be sampled between sync pulses.
+
+Values for first four channels (analog joystick values) can be found in
+first 10 nibbles. Analog value is represented by one sign bit and 9 bit
+absolute binary value. (10 bits per channel). Next nibble is checksum for
+first ten nibbles.
+
+Next nibbles 12 .. 21 represents four channels (not all channels can be
+directly controlled from TX). Binary representations are the same as in first
+four channels. In nibbles 22 and 23 is a special magic number. Nibble 24 is
+checksum for nibbles 12..23.
+
+After last octal value for nibble 24 and next sync pulse one additional
+binary value can be sampled. This bit and magic number is not used in
+software driver. Some details about this magic numbers can be found in
+Walkera_Wk-0701_PCM.pdf.
+
+Checksum calculation
+--------------------
+
+Summary of octal values in nibbles must be same as octal value in checksum
+nibble (only first 3 bits are used). Binary value for checksum nibble is
+calculated by sum of binary values in checked nibbles + sum of octal values
+in checked nibbles divided by 8. Only bit 0 of this sum is used.
diff --git a/Documentation/input/devices/xpad.rst b/Documentation/input/devices/xpad.rst
new file mode 100644 (file)
index 0000000..8002843
--- /dev/null
@@ -0,0 +1,240 @@
+=======================================================
+xpad - Linux USB driver for Xbox compatible controllers
+=======================================================
+
+This driver exposes all first-party and third-party Xbox compatible
+controllers. It has a long history and has enjoyed considerable usage
+as Window's xinput library caused most PC games to focus on Xbox
+controller compatibility.
+
+Due to backwards compatibility all buttons are reported as digital.
+This only effects Original Xbox controllers. All later controller models
+have only digital face buttons.
+
+Rumble is supported on some models of Xbox 360 controllers but not of
+Original Xbox controllers nor on Xbox One controllers. As of writing
+the Xbox One's rumble protocol has not been reverse engineered but in
+the future could be supported.
+
+
+Notes
+=====
+
+The number of buttons/axes reported varies based on 3 things:
+
+- if you are using a known controller
+- if you are using a known dance pad
+- if using an unknown device (one not listed below), what you set in the
+  module configuration for "Map D-PAD to buttons rather than axes for unknown
+  pads" (module option dpad_to_buttons)
+
+If you set dpad_to_buttons to N and you are using an unknown device
+the driver will map the directional pad to axes (X/Y).
+If you said Y it will map the d-pad to buttons, which is needed for dance
+style games to function correctly. The default is Y.
+
+dpad_to_buttons has no effect for known pads. A erroneous commit message
+claimed dpad_to_buttons could be used to force behavior on known devices.
+This is not true. Both dpad_to_buttons and triggers_to_buttons only affect
+unknown controllers.
+
+
+Normal Controllers
+------------------
+
+With a normal controller, the directional pad is mapped to its own X/Y axes.
+The jstest-program from joystick-1.2.15 (jstest-version 2.1.0) will report 8
+axes and 10 buttons.
+
+All 8 axes work, though they all have the same range (-32768..32767)
+and the zero-setting is not correct for the triggers (I don't know if that
+is some limitation of jstest, since the input device setup should be fine. I
+didn't have a look at jstest itself yet).
+
+All of the 10 buttons work (in digital mode). The six buttons on the
+right side (A, B, X, Y, black, white) are said to be "analog" and
+report their values as 8 bit unsigned, not sure what this is good for.
+
+I tested the controller with quake3, and configuration and
+in game functionality were OK. However, I find it rather difficult to
+play first person shooters with a pad. Your mileage may vary.
+
+
+Xbox Dance Pads
+---------------
+
+When using a known dance pad, jstest will report 6 axes and 14 buttons.
+
+For dance style pads (like the redoctane pad) several changes
+have been made.  The old driver would map the d-pad to axes, resulting
+in the driver being unable to report when the user was pressing both
+left+right or up+down, making DDR style games unplayable.
+
+Known dance pads automatically map the d-pad to buttons and will work
+correctly out of the box.
+
+If your dance pad is recognized by the driver but is using axes instead
+of buttons, see section 0.3 - Unknown Controllers
+
+I've tested this with Stepmania, and it works quite well.
+
+
+Unknown Controllers
+-------------------
+
+If you have an unknown xbox controller, it should work just fine with
+the default settings.
+
+HOWEVER if you have an unknown dance pad not listed below, it will not
+work UNLESS you set "dpad_to_buttons" to 1 in the module configuration.
+
+PLEASE, if you have an unknown controller, email Dom <binary1230@yahoo.com> with
+a dump from /proc/bus/usb and a description of the pad (manufacturer, country,
+whether it is a dance pad or normal controller) so that we can add your pad
+to the list of supported devices, ensuring that it will work out of the
+box in the future.
+
+
+USB adapters
+============
+
+All generations of Xbox controllers speak USB over the wire.
+
+- Original Xbox controllers use a proprietary connector and require adapters.
+- Wireless Xbox 360 controllers require a 'Xbox 360 Wireless Gaming Receiver
+  for Windows'
+- Wired Xbox 360 controllers use standard USB connectors.
+- Xbox One controllers can be wireless but speak Wi-Fi Direct and are not
+  yet supported.
+- Xbox One controllers can be wired and use standard Micro-USB connectors.
+
+
+
+Original Xbox USB adapters
+--------------------------
+
+Using this driver with an Original Xbox controller requires an
+adapter cable to break out the proprietary connector's pins to USB.
+You can buy these online fairly cheap, or build your own.
+
+Such a cable is pretty easy to build. The Controller itself is a USB
+compound device (a hub with three ports for two expansion slots and
+the controller device) with the only difference in a nonstandard connector
+(5 pins vs. 4 on standard USB 1.0 connectors).
+
+You just need to solder a USB connector onto the cable and keep the
+yellow wire unconnected. The other pins have the same order on both
+connectors so there is no magic to it. Detailed info on these matters
+can be found on the net ([1]_, [2]_, [3]_).
+
+Thanks to the trip splitter found on the cable you don't even need to cut the
+original one. You can buy an extension cable and cut that instead. That way,
+you can still use the controller with your X-Box, if you have one ;)
+
+
+
+Driver Installation
+===================
+
+Once you have the adapter cable, if needed, and the controller connected
+the xpad module should be auto loaded. To confirm you can cat
+/proc/bus/usb/devices. There should be an entry like the one at the end [4]_.
+
+
+
+Supported Controllers
+=====================
+
+For a full list of supported controllers and associated vendor and product
+IDs see the xpad_device[] array[6].
+
+As of the historic version 0.0.6 (2006-10-10) the following devices
+were supported::
+
+ original Microsoft XBOX controller (US),    vendor=0x045e, product=0x0202
+ smaller  Microsoft XBOX controller (US),    vendor=0x045e, product=0x0289
+ original Microsoft XBOX controller (Japan), vendor=0x045e, product=0x0285
+ InterAct PowerPad Pro (Germany),            vendor=0x05fd, product=0x107a
+ RedOctane Xbox Dance Pad (US),              vendor=0x0c12, product=0x8809
+
+Unrecognized models of Xbox controllers should function as Generic
+Xbox controllers. Unrecognized Dance Pad controllers require setting
+the module option 'dpad_to_buttons'.
+
+If you have an unrecognized controller please see 0.3 - Unknown Controllers
+
+
+Manual Testing
+==============
+
+To test this driver's functionality you may use 'jstest'.
+
+For example::
+
+    > modprobe xpad
+    > modprobe joydev
+    > jstest /dev/js0
+
+If you're using a normal controller, there should be a single line showing
+18 inputs (8 axes, 10 buttons), and its values should change if you move
+the sticks and push the buttons.  If you're using a dance pad, it should
+show 20 inputs (6 axes, 14 buttons).
+
+It works? Voila, you're done ;)
+
+
+
+Thanks
+======
+
+I have to thank ITO Takayuki for the detailed info on his site
+    http://euc.jp/periphs/xbox-controller.ja.html.
+
+His useful info and both the usb-skeleton as well as the iforce input driver
+(Greg Kroah-Hartmann; Vojtech Pavlik) helped a lot in rapid prototyping
+the basic functionality.
+
+
+
+References
+==========
+
+.. [1] http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
+.. [2] http://xpad.xbox-scene.com/
+.. [3] http://www.markosweb.com/www/xboxhackz.com/
+.. [4] /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany):
+
+ ::
+
+    T:  Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#=  5 Spd=12  MxCh= 0
+    D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs=  1
+    P:  Vendor=05fd ProdID=107a Rev= 1.00
+    C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
+    I:  If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none)
+    E:  Ad=81(I) Atr=03(Int.) MxPS=  32 Ivl= 10ms
+    E:  Ad=02(O) Atr=03(Int.) MxPS=  32 Ivl= 10ms
+.. [5] /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US):
+
+ ::
+
+    T:  Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12  MxCh= 0
+    D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
+    P:  Vendor=0c12 ProdID=8809 Rev= 0.01
+    S:  Product=XBOX DDR
+    C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
+    I:  If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad
+    E:  Ad=82(I) Atr=03(Int.) MxPS=  32 Ivl=4ms
+    E:  Ad=02(O) Atr=03(Int.) MxPS=  32 Ivl=4ms
+.. [6] http://lxr.free-electrons.com/ident?i=xpad_device
+
+
+Historic Edits
+==============
+
+2002-07-16 - Marko Friedemann <mfr@bmx-chemnitz.de>
+ - original doc
+
+2005-03-19 - Dominic Cerquetti <binary1230@yahoo.com>
+ - added stuff for dance pads, new d-pad->axes mappings
+
+Later changes may be viewed with 'git log Documentation/input/xpad.txt'
diff --git a/Documentation/input/devices/yealink.rst b/Documentation/input/devices/yealink.rst
new file mode 100644 (file)
index 0000000..bb5a1aa
--- /dev/null
@@ -0,0 +1,225 @@
+===============================================
+Driver documentation for yealink usb-p1k phones
+===============================================
+
+Status
+======
+
+The p1k is a relatively cheap usb 1.1 phone with:
+
+  - keyboard           full support, yealink.ko / input event API
+  - LCD                        full support, yealink.ko / sysfs API
+  - LED                        full support, yealink.ko / sysfs API
+  - dialtone           full support, yealink.ko / sysfs API
+  - ringtone           full support, yealink.ko / sysfs API
+  - audio playback     full support, snd_usb_audio.ko / alsa API
+  - audio record       full support, snd_usb_audio.ko / alsa API
+
+For vendor documentation see http://www.yealink.com
+
+
+keyboard features
+=================
+
+The current mapping in the kernel is provided by the map_p1k_to_key
+function::
+
+   Physical USB-P1K button layout      input events
+
+
+              up                            up
+        IN           OUT               left,   right
+             down                          down
+
+      pickup   C    hangup             enter, backspace, escape
+        1      2      3                        1, 2, 3
+        4      5      6                        4, 5, 6,
+        7      8      9                        7, 8, 9,
+        *      0      #                        *, 0, #,
+
+The "up" and "down" keys, are symbolised by arrows on the button.
+The "pickup" and "hangup" keys are symbolised by a green and red phone
+on the button.
+
+
+LCD features
+============
+
+The LCD is divided and organised as a 3 line display::
+
+    |[]   [][]   [][]   [][]   in   |[][]
+    |[] M [][] D [][] : [][]   out  |[][]
+                              store
+
+    NEW REP         SU MO TU WE TH FR SA
+
+    [] [] [] [] [] [] [] [] [] [] [] []
+    [] [] [] [] [] [] [] [] [] [] [] []
+
+
+  Line 1  Format (see below)   : 18.e8.M8.88...188
+         Icon names            :   M  D  :  IN OUT STORE
+  Line 2  Format               : .........
+         Icon name             : NEW REP SU MO TU WE TH FR SA
+  Line 3  Format               : 888888888888
+
+
+Format description:
+  From a userspace perspective the world is separated into "digits" and "icons".
+  A digit can have a character set, an icon can only be ON or OFF.
+
+  Format specifier::
+
+    '8' :  Generic 7 segment digit with individual addressable segments
+
+    Reduced capability 7 segment digit, when segments are hard wired together.
+    '1' : 2 segments digit only able to produce a 1.
+    'e' : Most significant day of the month digit,
+          able to produce at least 1 2 3.
+    'M' : Most significant minute digit,
+          able to produce at least 0 1 2 3 4 5.
+
+    Icons or pictograms:
+    '.' : For example like AM, PM, SU, a 'dot' .. or other single segment
+         elements.
+
+
+Driver usage
+============
+
+For userland the following interfaces are available using the sysfs interface::
+
+  /sys/.../
+           line1       Read/Write, lcd line1
+           line2       Read/Write, lcd line2
+           line3       Read/Write, lcd line3
+
+          get_icons    Read, returns a set of available icons.
+          hide_icon    Write, hide the element by writing the icon name.
+          show_icon    Write, display the element by writing the icon name.
+
+          map_seg7     Read/Write, the 7 segments char set, common for all
+                       yealink phones. (see map_to_7segment.h)
+
+          ringtone     Write, upload binary representation of a ringtone,
+                       see yealink.c. status EXPERIMENTAL due to potential
+                       races between async. and sync usb calls.
+
+
+lineX
+~~~~~
+
+Reading /sys/../lineX will return the format string with its current value.
+
+  Example::
+
+    cat ./line3
+    888888888888
+    Linux Rocks!
+
+Writing to /sys/../lineX will set the corresponding LCD line.
+
+ - Excess characters are ignored.
+ - If less characters are written than allowed, the remaining digits are
+   unchanged.
+ - The tab '\t'and '\n' char does not overwrite the original content.
+ - Writing a space to an icon will always hide its content.
+
+  Example::
+
+    date +"%m.%e.%k:%M"  | sed 's/^0/ /' > ./line1
+
+  Will update the LCD with the current date & time.
+
+
+get_icons
+~~~~~~~~~
+
+Reading will return all available icon names and its current settings::
+
+  cat ./get_icons
+  on M
+  on D
+  on :
+     IN
+     OUT
+     STORE
+     NEW
+     REP
+     SU
+     MO
+     TU
+     WE
+     TH
+     FR
+     SA
+     LED
+     DIALTONE
+     RINGTONE
+
+
+show/hide icons
+~~~~~~~~~~~~~~~
+
+Writing to these files will update the state of the icon.
+Only one icon at a time can be updated.
+
+If an icon is also on a ./lineX the corresponding value is
+updated with the first letter of the icon.
+
+  Example - light up the store icon::
+
+    echo -n "STORE" > ./show_icon
+
+    cat ./line1
+    18.e8.M8.88...188
+                 S
+
+  Example - sound the ringtone for 10 seconds::
+
+    echo -n RINGTONE > /sys/..../show_icon
+    sleep 10
+    echo -n RINGTONE > /sys/..../hide_icon
+
+
+Sound features
+==============
+
+Sound is supported by the ALSA driver: snd_usb_audio
+
+One 16-bit channel with sample and playback rates of 8000 Hz is the practical
+limit of the device.
+
+  Example - recording test::
+
+    arecord -v -d 10 -r 8000 -f S16_LE -t wav  foobar.wav
+
+  Example - playback test::
+
+    aplay foobar.wav
+
+
+Troubleshooting
+===============
+
+:Q: Module yealink compiled and installed without any problem but phone
+    is not initialized and does not react to any actions.
+:A: If you see something like:
+    hiddev0: USB HID v1.00 Device [Yealink Network Technology Ltd. VOIP USB Phone
+    in dmesg, it means that the hid driver has grabbed the device first. Try to
+    load module yealink before any other usb hid driver. Please see the
+    instructions provided by your distribution on module configuration.
+
+:Q: Phone is working now (displays version and accepts keypad input) but I can't
+    find the sysfs files.
+:A: The sysfs files are located on the particular usb endpoint. On most
+    distributions you can do: "find /sys/ -name get_icons" for a hint.
+
+
+Credits & Acknowledgments
+=========================
+
+  - Olivier Vandorpe, for starting the usbb2k-api project doing much of
+    the reverse engineering.
+  - Martin Diehl, for pointing out how to handle USB memory allocation.
+  - Dmitry Torokhov, for the numerous code reviews and suggestions.
diff --git a/Documentation/input/edt-ft5x06.rst b/Documentation/input/edt-ft5x06.rst
deleted file mode 100644 (file)
index 2032f0b..0000000
+++ /dev/null
@@ -1,54 +0,0 @@
-EDT ft5x06 based Polytouch devices
-----------------------------------
-
-The edt-ft5x06 driver is useful for the EDT "Polytouch" family of capacitive
-touch screens. Note that it is *not* suitable for other devices based on the
-focaltec ft5x06 devices, since they contain vendor-specific firmware. In
-particular this driver is not suitable for the Nook tablet.
-
-It has been tested with the following devices:
-  * EP0350M06
-  * EP0430M06
-  * EP0570M06
-  * EP0700M06
-
-The driver allows configuration of the touch screen via a set of sysfs files:
-
-/sys/class/input/eventX/device/device/threshold:
-    allows setting the "click"-threshold in the range from 20 to 80.
-
-/sys/class/input/eventX/device/device/gain:
-    allows setting the sensitivity in the range from 0 to 31. Note that
-    lower values indicate higher sensitivity.
-
-/sys/class/input/eventX/device/device/offset:
-    allows setting the edge compensation in the range from 0 to 31.
-
-/sys/class/input/eventX/device/device/report_rate:
-    allows setting the report rate in the range from 3 to 14.
-
-
-For debugging purposes the driver provides a few files in the debug
-filesystem (if available in the kernel). In /sys/kernel/debug/edt_ft5x06
-you'll find the following files:
-
-num_x, num_y:
-    (readonly) contains the number of sensor fields in X- and
-    Y-direction.
-
-mode:
-    allows switching the sensor between "factory mode" and "operation
-    mode" by writing "1" or "0" to it. In factory mode (1) it is
-    possible to get the raw data from the sensor. Note that in factory
-    mode regular events don't get delivered and the options described
-    above are unavailable.
-
-raw_data:
-    contains num_x * num_y big endian 16 bit values describing the raw
-    values for each sensor field. Note that each read() call on this
-    files triggers a new readout. It is recommended to provide a buffer
-    big enough to contain num_x * num_y * 2 bytes.
-
-Note that reading raw_data gives a I/O error when the device is not in factory
-mode. The same happens when reading/writing to the parameter files when the
-device is not in regular operation mode.
diff --git a/Documentation/input/elantech.rst b/Documentation/input/elantech.rst
deleted file mode 100644 (file)
index c3374a7..0000000
+++ /dev/null
@@ -1,841 +0,0 @@
-Elantech Touchpad Driver
-========================
-
-       Copyright (C) 2007-2008 Arjan Opmeer <arjan@opmeer.net>
-
-       Extra information for hardware version 1 found and
-       provided by Steve Havelka
-
-       Version 2 (EeePC) hardware support based on patches
-       received from Woody at Xandros and forwarded to me
-       by user StewieGriffin at the eeeuser.com forum
-
-.. Contents
-
- 1. Introduction
- 2. Extra knobs
- 3. Differentiating hardware versions
- 4. Hardware version 1
-    4.1 Registers
-    4.2 Native relative mode 4 byte packet format
-    4.3 Native absolute mode 4 byte packet format
- 5. Hardware version 2
-    5.1 Registers
-    5.2 Native absolute mode 6 byte packet format
-        5.2.1 Parity checking and packet re-synchronization
-        5.2.2 One/Three finger touch
-        5.2.3 Two finger touch
- 6. Hardware version 3
-    6.1 Registers
-    6.2 Native absolute mode 6 byte packet format
-        6.2.1 One/Three finger touch
-        6.2.2 Two finger touch
- 7. Hardware version 4
-    7.1 Registers
-    7.2 Native absolute mode 6 byte packet format
-        7.2.1 Status packet
-        7.2.2 Head packet
-        7.2.3 Motion packet
- 8. Trackpoint (for Hardware version 3 and 4)
-    8.1 Registers
-    8.2 Native relative mode 6 byte packet format
-        8.2.1 Status Packet
-
-
-
-Introduction
-~~~~~~~~~~~~
-
-Currently the Linux Elantech touchpad driver is aware of four different
-hardware versions unimaginatively called version 1,version 2, version 3
-and version 4. Version 1 is found in "older" laptops and uses 4 bytes per
-packet. Version 2 seems to be introduced with the EeePC and uses 6 bytes
-per packet, and provides additional features such as position of two fingers,
-and width of the touch.  Hardware version 3 uses 6 bytes per packet (and
-for 2 fingers the concatenation of two 6 bytes packets) and allows tracking
-of up to 3 fingers. Hardware version 4 uses 6 bytes per packet, and can
-combine a status packet with multiple head or motion packets. Hardware version
-4 allows tracking up to 5 fingers.
-
-Some Hardware version 3 and version 4 also have a trackpoint which uses a
-separate packet format. It is also 6 bytes per packet.
-
-The driver tries to support both hardware versions and should be compatible
-with the Xorg Synaptics touchpad driver and its graphical configuration
-utilities.
-
-Note that a mouse button is also associated with either the touchpad or the
-trackpoint when a trackpoint is available.  Disabling the Touchpad in xorg
-(TouchPadOff=0) will also disable the buttons associated with the touchpad.
-
-Additionally the operation of the touchpad can be altered by adjusting the
-contents of some of its internal registers. These registers are represented
-by the driver as sysfs entries under /sys/bus/serio/drivers/psmouse/serio?
-that can be read from and written to.
-
-Currently only the registers for hardware version 1 are somewhat understood.
-Hardware version 2 seems to use some of the same registers but it is not
-known whether the bits in the registers represent the same thing or might
-have changed their meaning.
-
-On top of that, some register settings have effect only when the touchpad is
-in relative mode and not in absolute mode. As the Linux Elantech touchpad
-driver always puts the hardware into absolute mode not all information
-mentioned below can be used immediately. But because there is no freely
-available Elantech documentation the information is provided here anyway for
-completeness sake.
-
-
-Extra knobs
-~~~~~~~~~~~
-
-Currently the Linux Elantech touchpad driver provides three extra knobs under
-/sys/bus/serio/drivers/psmouse/serio? for the user.
-
-* debug
-
-   Turn different levels of debugging ON or OFF.
-
-   By echoing "0" to this file all debugging will be turned OFF.
-
-   Currently a value of "1" will turn on some basic debugging and a value of
-   "2" will turn on packet debugging. For hardware version 1 the default is
-   OFF. For version 2 the default is "1".
-
-   Turning packet debugging on will make the driver dump every packet
-   received to the syslog before processing it. Be warned that this can
-   generate quite a lot of data!
-
-* paritycheck
-
-   Turns parity checking ON or OFF.
-
-   By echoing "0" to this file parity checking will be turned OFF. Any
-   non-zero value will turn it ON. For hardware version 1 the default is ON.
-   For version 2 the default it is OFF.
-
-   Hardware version 1 provides basic data integrity verification by
-   calculating a parity bit for the last 3 bytes of each packet. The driver
-   can check these bits and reject any packet that appears corrupted. Using
-   this knob you can bypass that check.
-
-   Hardware version 2 does not provide the same parity bits. Only some basic
-   data consistency checking can be done. For now checking is disabled by
-   default. Currently even turning it on will do nothing.
-
-* crc_enabled
-
-   Sets crc_enabled to 0/1. The name "crc_enabled" is the official name of
-   this integrity check, even though it is not an actual cyclic redundancy
-   check.
-
-   Depending on the state of crc_enabled, certain basic data integrity
-   verification is done by the driver on hardware version 3 and 4. The
-   driver will reject any packet that appears corrupted. Using this knob,
-   The state of crc_enabled can be altered with this knob.
-
-   Reading the crc_enabled value will show the active value. Echoing
-   "0" or "1" to this file will set the state to "0" or "1".
-
-Differentiating hardware versions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To detect the hardware version, read the version number as param[0].param[1].param[2]::
-
- 4 bytes version: (after the arrow is the name given in the Dell-provided driver)
- 02.00.22 => EF013
- 02.06.00 => EF019
-
-In the wild, there appear to be more versions, such as 00.01.64, 01.00.21,
-02.00.00, 02.00.04, 02.00.06::
-
- 6 bytes:
- 02.00.30 => EF113
- 02.08.00 => EF023
- 02.08.XX => EF123
- 02.0B.00 => EF215
- 04.01.XX => Scroll_EF051
- 04.02.XX => EF051
-
-In the wild, there appear to be more versions, such as 04.03.01, 04.04.11. There
-appears to be almost no difference, except for EF113, which does not report
-pressure/width and has different data consistency checks.
-
-Probably all the versions with param[0] <= 01 can be considered as
-4 bytes/firmware 1. The versions < 02.08.00, with the exception of 02.00.30, as
-4 bytes/firmware 2. Everything >= 02.08.00 can be considered as 6 bytes.
-
-
-Hardware version 1
-~~~~~~~~~~~~~~~~~~
-
-Registers
----------
-
-By echoing a hexadecimal value to a register it contents can be altered.
-
-For example::
-
-   echo -n 0x16 > reg_10
-
-* reg_10::
-
-   bit   7   6   5   4   3   2   1   0
-         B   C   T   D   L   A   S   E
-
-         E: 1 = enable smart edges unconditionally
-         S: 1 = enable smart edges only when dragging
-         A: 1 = absolute mode (needs 4 byte packets, see reg_11)
-         L: 1 = enable drag lock (see reg_22)
-         D: 1 = disable dynamic resolution
-         T: 1 = disable tapping
-         C: 1 = enable corner tap
-         B: 1 = swap left and right button
-
-* reg_11::
-
-   bit   7   6   5   4   3   2   1   0
-         1   0   0   H   V   1   F   P
-
-         P: 1 = enable parity checking for relative mode
-         F: 1 = enable native 4 byte packet mode
-         V: 1 = enable vertical scroll area
-         H: 1 = enable horizontal scroll area
-
-* reg_20::
-
-         single finger width?
-
-* reg_21::
-
-         scroll area width (small: 0x40 ... wide: 0xff)
-
-* reg_22::
-
-         drag lock time out (short: 0x14 ... long: 0xfe;
-                             0xff = tap again to release)
-
-* reg_23::
-
-         tap make timeout?
-
-* reg_24::
-
-         tap release timeout?
-
-* reg_25::
-
-         smart edge cursor speed (0x02 = slow, 0x03 = medium, 0x04 = fast)
-
-* reg_26::
-
-         smart edge activation area width?
-
-
-Native relative mode 4 byte packet format
------------------------------------------
-
-byte 0::
-
-   bit   7   6   5   4   3   2   1   0
-         c   c  p2  p1   1   M   R   L
-
-         L, R, M = 1 when Left, Right, Middle mouse button pressed
-            some models have M as byte 3 odd parity bit
-         when parity checking is enabled (reg_11, P = 1):
-            p1..p2 = byte 1 and 2 odd parity bit
-         c = 1 when corner tap detected
-
-byte 1::
-
-   bit   7   6   5   4   3   2   1   0
-        dx7 dx6 dx5 dx4 dx3 dx2 dx1 dx0
-
-         dx7..dx0 = x movement;   positive = right, negative = left
-         byte 1 = 0xf0 when corner tap detected
-
-byte 2::
-
-   bit   7   6   5   4   3   2   1   0
-        dy7 dy6 dy5 dy4 dy3 dy2 dy1 dy0
-
-         dy7..dy0 = y movement;   positive = up,    negative = down
-
-byte 3::
-
-   parity checking enabled (reg_11, P = 1):
-
-      bit   7   6   5   4   3   2   1   0
-            w   h  n1  n0  ds3 ds2 ds1 ds0
-
-            normally:
-               ds3..ds0 = scroll wheel amount and direction
-                          positive = down or left
-                          negative = up or right
-            when corner tap detected:
-               ds0 = 1 when top right corner tapped
-               ds1 = 1 when bottom right corner tapped
-               ds2 = 1 when bottom left corner tapped
-               ds3 = 1 when top left corner tapped
-            n1..n0 = number of fingers on touchpad
-               only models with firmware 2.x report this, models with
-               firmware 1.x seem to map one, two and three finger taps
-               directly to L, M and R mouse buttons
-            h = 1 when horizontal scroll action
-            w = 1 when wide finger touch?
-
-   otherwise (reg_11, P = 0):
-
-      bit   7   6   5   4   3   2   1   0
-           ds7 ds6 ds5 ds4 ds3 ds2 ds1 ds0
-
-            ds7..ds0 = vertical scroll amount and direction
-                       negative = up
-                       positive = down
-
-
-Native absolute mode 4 byte packet format
------------------------------------------
-
-EF013 and EF019 have a special behaviour (due to a bug in the firmware?), and
-when 1 finger is touching, the first 2 position reports must be discarded.
-This counting is reset whenever a different number of fingers is reported.
-
-byte 0::
-
-   firmware version 1.x:
-
-      bit   7   6   5   4   3   2   1   0
-            D   U  p1  p2   1  p3   R   L
-
-            L, R = 1 when Left, Right mouse button pressed
-            p1..p3 = byte 1..3 odd parity bit
-            D, U = 1 when rocker switch pressed Up, Down
-
-   firmware version 2.x:
-
-      bit   7   6   5   4   3   2   1   0
-           n1  n0  p2  p1   1  p3   R   L
-
-            L, R = 1 when Left, Right mouse button pressed
-            p1..p3 = byte 1..3 odd parity bit
-            n1..n0 = number of fingers on touchpad
-
-byte 1::
-
-   firmware version 1.x:
-
-      bit   7   6   5   4   3   2   1   0
-            f   0  th  tw  x9  x8  y9  y8
-
-            tw = 1 when two finger touch
-            th = 1 when three finger touch
-            f  = 1 when finger touch
-
-   firmware version 2.x:
-
-      bit   7   6   5   4   3   2   1   0
-            .   .   .   .  x9  x8  y9  y8
-
-byte 2::
-
-   bit   7   6   5   4   3   2   1   0
-        x7  x6  x5  x4  x3  x2  x1  x0
-
-         x9..x0 = absolute x value (horizontal)
-
-byte 3::
-
-   bit   7   6   5   4   3   2   1   0
-        y7  y6  y5  y4  y3  y2  y1  y0
-
-         y9..y0 = absolute y value (vertical)
-
-
-Hardware version 2
-~~~~~~~~~~~~~~~~~~
-
-
-Registers
----------
-
-By echoing a hexadecimal value to a register it contents can be altered.
-
-For example::
-
-   echo -n 0x56 > reg_10
-
-* reg_10::
-
-   bit   7   6   5   4   3   2   1   0
-         0   1   0   1   0   1   D   0
-
-         D: 1 = enable drag and drop
-
-* reg_11::
-
-   bit   7   6   5   4   3   2   1   0
-         1   0   0   0   S   0   1   0
-
-         S: 1 = enable vertical scroll
-
-* reg_21::
-
-         unknown (0x00)
-
-* reg_22::
-
-         drag and drop release time out (short: 0x70 ... long 0x7e;
-                                   0x7f = never i.e. tap again to release)
-
-
-Native absolute mode 6 byte packet format
------------------------------------------
-
-Parity checking and packet re-synchronization
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-There is no parity checking, however some consistency checks can be performed.
-
-For instance for EF113::
-
-        SA1= packet[0];
-        A1 = packet[1];
-        B1 = packet[2];
-        SB1= packet[3];
-        C1 = packet[4];
-        D1 = packet[5];
-        if( (((SA1 & 0x3C) != 0x3C) && ((SA1 & 0xC0) != 0x80)) || // check Byte 1
-            (((SA1 & 0x0C) != 0x0C) && ((SA1 & 0xC0) == 0x80)) || // check Byte 1 (one finger pressed)
-            (((SA1 & 0xC0) != 0x80) && (( A1 & 0xF0) != 0x00)) || // check Byte 2
-            (((SB1 & 0x3E) != 0x38) && ((SA1 & 0xC0) != 0x80)) || // check Byte 4
-            (((SB1 & 0x0E) != 0x08) && ((SA1 & 0xC0) == 0x80)) || // check Byte 4 (one finger pressed)
-            (((SA1 & 0xC0) != 0x80) && (( C1 & 0xF0) != 0x00))  ) // check Byte 5
-               // error detected
-
-For all the other ones, there are just a few constant bits::
-
-        if( ((packet[0] & 0x0C) != 0x04) ||
-            ((packet[3] & 0x0f) != 0x02) )
-               // error detected
-
-
-In case an error is detected, all the packets are shifted by one (and packet[0] is discarded).
-
-One/Three finger touch
-^^^^^^^^^^^^^^^^^^^^^^
-
-byte 0::
-
-   bit   7   6   5   4   3   2   1   0
-        n1  n0  w3  w2   .   .   R   L
-
-         L, R = 1 when Left, Right mouse button pressed
-         n1..n0 = number of fingers on touchpad
-
-byte 1::
-
-   bit   7   6   5   4   3   2   1   0
-        p7  p6  p5  p4 x11 x10 x9  x8
-
-byte 2::
-
-   bit   7   6   5   4   3   2   1   0
-        x7  x6  x5  x4  x3  x2  x1  x0
-
-         x11..x0 = absolute x value (horizontal)
-
-byte 3::
-
-   bit   7   6   5   4   3   2   1   0
-        n4  vf  w1  w0   .   .   .  b2
-
-        n4 = set if more than 3 fingers (only in 3 fingers mode)
-        vf = a kind of flag ? (only on EF123, 0 when finger is over one
-             of the buttons, 1 otherwise)
-        w3..w0 = width of the finger touch (not EF113)
-        b2 (on EF113 only, 0 otherwise), b2.R.L indicates one button pressed:
-               0 = none
-               1 = Left
-               2 = Right
-               3 = Middle (Left and Right)
-               4 = Forward
-               5 = Back
-               6 = Another one
-               7 = Another one
-
-byte 4::
-
-   bit   7   6   5   4   3   2   1   0
-        p3  p1  p2  p0  y11 y10 y9  y8
-
-        p7..p0 = pressure (not EF113)
-
-byte 5::
-
-   bit   7   6   5   4   3   2   1   0
-        y7  y6  y5  y4  y3  y2  y1  y0
-
-         y11..y0 = absolute y value (vertical)
-
-
-Two finger touch
-^^^^^^^^^^^^^^^^
-
-Note that the two pairs of coordinates are not exactly the coordinates of the
-two fingers, but only the pair of the lower-left and upper-right coordinates.
-So the actual fingers might be situated on the other diagonal of the square
-defined by these two points.
-
-byte 0::
-
-   bit   7   6   5   4   3   2   1   0
-        n1  n0  ay8 ax8  .   .   R   L
-
-         L, R = 1 when Left, Right mouse button pressed
-         n1..n0 = number of fingers on touchpad
-
-byte 1::
-
-   bit   7   6   5   4   3   2   1   0
-        ax7 ax6 ax5 ax4 ax3 ax2 ax1 ax0
-
-        ax8..ax0 = lower-left finger absolute x value
-
-byte 2::
-
-   bit   7   6   5   4   3   2   1   0
-        ay7 ay6 ay5 ay4 ay3 ay2 ay1 ay0
-
-        ay8..ay0 = lower-left finger absolute y value
-
-byte 3::
-
-   bit   7   6   5   4   3   2   1   0
-         .   .  by8 bx8  .   .   .   .
-
-byte 4::
-
-   bit   7   6   5   4   3   2   1   0
-        bx7 bx6 bx5 bx4 bx3 bx2 bx1 bx0
-
-         bx8..bx0 = upper-right finger absolute x value
-
-byte 5::
-
-   bit   7   6   5   4   3   2   1   0
-        by7 by8 by5 by4 by3 by2 by1 by0
-
-         by8..by0 = upper-right finger absolute y value
-
-Hardware version 3
-~~~~~~~~~~~~~~~~~~
-
-Registers
----------
-
-* reg_10::
-
-   bit   7   6   5   4   3   2   1   0
-         0   0   0   0   R   F   T   A
-
-         A: 1 = enable absolute tracking
-         T: 1 = enable two finger mode auto correct
-         F: 1 = disable ABS Position Filter
-         R: 1 = enable real hardware resolution
-
-Native absolute mode 6 byte packet format
------------------------------------------
-
-1 and 3 finger touch shares the same 6-byte packet format, except that
-3 finger touch only reports the position of the center of all three fingers.
-
-Firmware would send 12 bytes of data for 2 finger touch.
-
-Note on debounce:
-In case the box has unstable power supply or other electricity issues, or
-when number of finger changes, F/W would send "debounce packet" to inform
-driver that the hardware is in debounce status.
-The debouce packet has the following signature::
-
-    byte 0: 0xc4
-    byte 1: 0xff
-    byte 2: 0xff
-    byte 3: 0x02
-    byte 4: 0xff
-    byte 5: 0xff
-
-When we encounter this kind of packet, we just ignore it.
-
-One/Three finger touch
-^^^^^^^^^^^^^^^^^^^^^^
-
-byte 0::
-
-   bit   7   6   5   4   3   2   1   0
-        n1  n0  w3  w2   0   1   R   L
-
-        L, R = 1 when Left, Right mouse button pressed
-        n1..n0 = number of fingers on touchpad
-
-byte 1::
-
-   bit   7   6   5   4   3   2   1   0
-        p7  p6  p5  p4 x11 x10  x9  x8
-
-byte 2::
-
-   bit   7   6   5   4   3   2   1   0
-        x7  x6  x5  x4  x3  x2  x1  x0
-
-        x11..x0 = absolute x value (horizontal)
-
-byte 3::
-
-   bit   7   6   5   4   3   2   1   0
-         0   0  w1  w0   0   0   1   0
-
-         w3..w0 = width of the finger touch
-
-byte 4::
-
-   bit   7   6   5   4   3   2   1   0
-        p3  p1  p2  p0  y11 y10 y9  y8
-
-        p7..p0 = pressure
-
-byte 5::
-
-   bit   7   6   5   4   3   2   1   0
-        y7  y6  y5  y4  y3  y2  y1  y0
-
-        y11..y0 = absolute y value (vertical)
-
-Two finger touch
-^^^^^^^^^^^^^^^^
-
-The packet format is exactly the same for two finger touch, except the hardware
-sends two 6 byte packets. The first packet contains data for the first finger,
-the second packet has data for the second finger. So for two finger touch a
-total of 12 bytes are sent.
-
-Hardware version 4
-~~~~~~~~~~~~~~~~~~
-
-Registers
----------
-
-* reg_07::
-
-   bit   7   6   5   4   3   2   1   0
-         0   0   0   0   0   0   0   A
-
-         A: 1 = enable absolute tracking
-
-Native absolute mode 6 byte packet format
------------------------------------------
-
-v4 hardware is a true multitouch touchpad, capable of tracking up to 5 fingers.
-Unfortunately, due to PS/2's limited bandwidth, its packet format is rather
-complex.
-
-Whenever the numbers or identities of the fingers changes, the hardware sends a
-status packet to indicate how many and which fingers is on touchpad, followed by
-head packets or motion packets. A head packet contains data of finger id, finger
-position (absolute x, y values), width, and pressure. A motion packet contains
-two fingers' position delta.
-
-For example, when status packet tells there are 2 fingers on touchpad, then we
-can expect two following head packets. If the finger status doesn't change,
-the following packets would be motion packets, only sending delta of finger
-position, until we receive a status packet.
-
-One exception is one finger touch. when a status packet tells us there is only
-one finger, the hardware would just send head packets afterwards.
-
-Status packet
-^^^^^^^^^^^^^
-
-byte 0::
-
-   bit   7   6   5   4   3   2   1   0
-         .   .   .   .   0   1   R   L
-
-         L, R = 1 when Left, Right mouse button pressed
-
-byte 1::
-
-   bit   7   6   5   4   3   2   1   0
-         .   .   . ft4 ft3 ft2 ft1 ft0
-
-         ft4 ft3 ft2 ft1 ft0 ftn = 1 when finger n is on touchpad
-
-byte 2::
-
-   not used
-
-byte 3::
-
-   bit   7   6   5   4   3   2   1   0
-         .   .   .   1   0   0   0   0
-
-         constant bits
-
-byte 4::
-
-   bit   7   6   5   4   3   2   1   0
-         p   .   .   .   .   .   .   .
-
-         p = 1 for palm
-
-byte 5::
-
-   not used
-
-Head packet
-^^^^^^^^^^^
-
-byte 0::
-
-   bit   7   6   5   4   3   2   1   0
-        w3  w2  w1  w0   0   1   R   L
-
-        L, R = 1 when Left, Right mouse button pressed
-        w3..w0 = finger width (spans how many trace lines)
-
-byte 1::
-
-   bit   7   6   5   4   3   2   1   0
-        p7  p6  p5  p4 x11 x10  x9  x8
-
-byte 2::
-
-   bit   7   6   5   4   3   2   1   0
-        x7  x6  x5  x4  x3  x2  x1  x0
-
-        x11..x0 = absolute x value (horizontal)
-
-byte 3::
-
-   bit   7   6   5   4   3   2   1   0
-       id2 id1 id0   1   0   0   0   1
-
-       id2..id0 = finger id
-
-byte 4::
-
-   bit   7   6   5   4   3   2   1   0
-        p3  p1  p2  p0  y11 y10 y9  y8
-
-        p7..p0 = pressure
-
-byte 5::
-
-   bit   7   6   5   4   3   2   1   0
-        y7  y6  y5  y4  y3  y2  y1  y0
-
-        y11..y0 = absolute y value (vertical)
-
-Motion packet
-^^^^^^^^^^^^^
-
-byte 0::
-
-   bit   7   6   5   4   3   2   1   0
-       id2 id1 id0   w   0   1   R   L
-
-       L, R = 1 when Left, Right mouse button pressed
-       id2..id0 = finger id
-       w = 1 when delta overflows (> 127 or < -128), in this case
-       firmware sends us (delta x / 5) and (delta y  / 5)
-
-byte 1::
-
-   bit   7   6   5   4   3   2   1   0
-        x7  x6  x5  x4  x3  x2  x1  x0
-
-        x7..x0 = delta x (two's complement)
-
-byte 2::
-
-   bit   7   6   5   4   3   2   1   0
-        y7  y6  y5  y4  y3  y2  y1  y0
-
-        y7..y0 = delta y (two's complement)
-
-byte 3::
-
-   bit   7   6   5   4   3   2   1   0
-       id2 id1 id0   1   0   0   1   0
-
-       id2..id0 = finger id
-
-byte 4::
-
-   bit   7   6   5   4   3   2   1   0
-        x7  x6  x5  x4  x3  x2  x1  x0
-
-        x7..x0 = delta x (two's complement)
-
-byte 5::
-
-   bit   7   6   5   4   3   2   1   0
-        y7  y6  y5  y4  y3  y2  y1  y0
-
-        y7..y0 = delta y (two's complement)
-
-        byte 0 ~ 2 for one finger
-        byte 3 ~ 5 for another
-
-
-Trackpoint (for Hardware version 3 and 4)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Registers
----------
-
-No special registers have been identified.
-
-Native relative mode 6 byte packet format
------------------------------------------
-
-Status Packet
-^^^^^^^^^^^^^
-
-byte 0::
-
-   bit   7   6   5   4   3   2   1   0
-         0   0  sx  sy   0   M   R   L
-
-byte 1::
-
-   bit   7   6   5   4   3   2   1   0
-       ~sx   0   0   0   0   0   0   0
-
-byte 2::
-
-   bit   7   6   5   4   3   2   1   0
-       ~sy   0   0   0   0   0   0   0
-
-byte 3::
-
-   bit   7   6   5   4   3   2   1   0
-         0   0 ~sy ~sx   0   1   1   0
-
-byte 4::
-
-   bit   7   6   5   4   3   2   1   0
-        x7  x6  x5  x4  x3  x2  x1  x0
-
-byte 5::
-
-   bit   7   6   5   4   3   2   1   0
-        y7  y6  y5  y4  y3  y2  y1  y0
-
-
-         x and y are written in two's complement spread
-             over 9 bits with sx/sy the relative top bit and
-             x7..x0 and y7..y0 the lower bits.
-        ~sx is the inverse of sx, ~sy is the inverse of sy.
-         The sign of y is opposite to what the input driver
-             expects for a relative movement
index 1bc4555c0ccb566fadf32b5644f068950c314c80..4d5e7fb80a8456599608817dc8ca00478e2ee1be 100644 (file)
@@ -1,12 +1,12 @@
------------------
-Linux Gamepad API
------------------
+---------------------------
+Linux Gamepad Specification
+---------------------------
 
 :Author: 2013 by David Herrmann <dh.herrmann@gmail.com>
 
 
-Intro
-~~~~~
+Introduction
+~~~~~~~~~~~~
 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.
diff --git a/Documentation/input/gpio-tilt.rst b/Documentation/input/gpio-tilt.rst
deleted file mode 100644 (file)
index 23de9ef..0000000
+++ /dev/null
@@ -1,103 +0,0 @@
-Driver for tilt-switches connected via GPIOs
-============================================
-
-Generic driver to read data from tilt switches connected via gpios.
-Orientation can be provided by one or more than one tilt switches,
-i.e. each tilt switch providing one axis, and the number of axes
-is also not limited.
-
-
-Data structures:
-----------------
-
-The array of struct gpio in the gpios field is used to list the gpios
-that represent the current tilt state.
-
-The array of struct gpio_tilt_axis describes the axes that are reported
-to the input system. The values set therein are used for the
-input_set_abs_params calls needed to init the axes.
-
-The array of struct gpio_tilt_state maps gpio states to the corresponding
-values to report. The gpio state is represented as a bitfield where the
-bit-index corresponds to the index of the gpio in the struct gpio array.
-In the same manner the values stored in the axes array correspond to
-the elements of the gpio_tilt_axis-array.
-
-
-Example:
---------
-
-Example configuration for a single TS1003 tilt switch that rotates around
-one axis in 4 steps and emits the current tilt via two GPIOs::
-
-    static int sg060_tilt_enable(struct device *dev) {
-           /* code to enable the sensors */
-    };
-
-    static void sg060_tilt_disable(struct device *dev) {
-           /* code to disable the sensors */
-    };
-
-    static struct gpio sg060_tilt_gpios[] = {
-           { SG060_TILT_GPIO_SENSOR1, GPIOF_IN, "tilt_sensor1" },
-           { SG060_TILT_GPIO_SENSOR2, GPIOF_IN, "tilt_sensor2" },
-    };
-
-    static struct gpio_tilt_state sg060_tilt_states[] = {
-           {
-                   .gpios = (0 << 1) | (0 << 0),
-                   .axes = (int[]) {
-                           0,
-                   },
-           }, {
-                   .gpios = (0 << 1) | (1 << 0),
-                   .axes = (int[]) {
-                           1, /* 90 degrees */
-                   },
-           }, {
-                   .gpios = (1 << 1) | (1 << 0),
-                   .axes = (int[]) {
-                           2, /* 180 degrees */
-                   },
-           }, {
-                   .gpios = (1 << 1) | (0 << 0),
-                   .axes = (int[]) {
-                           3, /* 270 degrees */
-                   },
-           },
-    };
-
-    static struct gpio_tilt_axis sg060_tilt_axes[] = {
-           {
-                   .axis = ABS_RY,
-                   .min = 0,
-                   .max = 3,
-                   .fuzz = 0,
-                   .flat = 0,
-           },
-    };
-
-    static struct gpio_tilt_platform_data sg060_tilt_pdata= {
-           .gpios = sg060_tilt_gpios,
-           .nr_gpios = ARRAY_SIZE(sg060_tilt_gpios),
-
-           .axes = sg060_tilt_axes,
-           .nr_axes = ARRAY_SIZE(sg060_tilt_axes),
-
-           .states = sg060_tilt_states,
-           .nr_states = ARRAY_SIZE(sg060_tilt_states),
-
-           .debounce_interval = 100,
-
-           .poll_interval = 1000,
-           .enable = sg060_tilt_enable,
-           .disable = sg060_tilt_disable,
-    };
-
-    static struct platform_device sg060_device_tilt = {
-           .name = "gpio-tilt-polled",
-           .id = -1,
-           .dev = {
-                   .platform_data = &sg060_tilt_pdata,
-           },
-    };
diff --git a/Documentation/input/iforce-protocol.rst b/Documentation/input/iforce-protocol.rst
deleted file mode 100644 (file)
index 8634bea..0000000
+++ /dev/null
@@ -1,381 +0,0 @@
-===============
-Iforce Protocol
-===============
-
-:Author: Johann Deneux <johann.deneux@gmail.com>
-
-Home page at `<http://web.archive.org/web/*/http://www.esil.univ-mrs.fr>`_
-
-:Additions: by Vojtech Pavlik.
-
-
-Introduction
-============
-
-This document describes what I managed to discover about the protocol used to
-specify force effects to I-Force 2.0 devices.  None of this information comes
-from Immerse. That's why you should not trust what is written in this
-document. This document is intended to help understanding the protocol.
-This is not a reference. Comments and corrections are welcome.  To contact me,
-send an email to: johann.deneux@gmail.com
-
-.. warning::
-
-    I shall not be held responsible for any damage or harm caused if you try to
-    send data to your I-Force device based on what you read in this document.
-
-Preliminary Notes
-=================
-
-All values are hexadecimal with big-endian encoding (msb on the left). Beware,
-values inside packets are encoded using little-endian.  Bytes whose roles are
-unknown are marked ???  Information that needs deeper inspection is marked (?)
-
-General form of a packet
-------------------------
-
-This is how packets look when the device uses the rs232 to communicate.
-
-== == === ==== ==
-2B OP LEN DATA CS
-== == === ==== ==
-
-CS is the checksum. It is equal to the exclusive or of all bytes.
-
-When using USB:
-
-== ====
-OP DATA
-== ====
-
-The 2B, LEN and CS fields have disappeared, probably because USB handles
-frames and data corruption is handled or unsignificant.
-
-First, I describe effects that are sent by the device to the computer
-
-Device input state
-==================
-
-This packet is used to indicate the state of each button and the value of each
-axis::
-
-    OP= 01 for a joystick, 03 for a wheel
-    LEN= Varies from device to device
-    00 X-Axis lsb
-    01 X-Axis msb
-    02 Y-Axis lsb, or gas pedal for a wheel
-    03 Y-Axis msb, or brake pedal for a wheel
-    04 Throttle
-    05 Buttons
-    06 Lower 4 bits: Buttons
-       Upper 4 bits: Hat
-    07 Rudder
-
-Device effects states
-=====================
-
-::
-
-    OP= 02
-    LEN= Varies
-    00 ? Bit 1 (Value 2) is the value of the deadman switch
-    01 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id.
-    02 ??
-    03 Address of parameter block changed (lsb)
-    04 Address of parameter block changed (msb)
-    05 Address of second parameter block changed (lsb)
-    ... depending on the number of parameter blocks updated
-
-Force effect
-------------
-
-::
-
-    OP=  01
-    LEN= 0e
-    00 Channel (when playing several effects at the same time, each must
-                be assigned a channel)
-    01 Wave form
-           Val 00 Constant
-           Val 20 Square
-           Val 21 Triangle
-           Val 22 Sine
-           Val 23 Sawtooth up
-           Val 24 Sawtooth down
-           Val 40 Spring (Force = f(pos))
-           Val 41 Friction (Force = f(velocity)) and Inertia
-                  (Force = f(acceleration))
-
-
-    02 Axes affected and trigger
-           Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction
-                   Val 4 = X axis only. Byte 05 must contain 5a
-                   Val 8 = Y axis only. Byte 05 must contain b4
-                   Val c = X and Y axes. Bytes 05 must contain 60
-           Bits 0-3: Val 0 = No trigger
-                   Val x+1 = Button x triggers the effect
-           When the whole byte is 0, cancel the previously set trigger
-
-    03-04 Duration of effect (little endian encoding, in ms)
-
-    05 Direction of effect, if applicable. Else, see 02 for value to assign.
-
-    06-07 Minimum time between triggering.
-
-    08-09 Address of periodicity or magnitude parameters
-    0a-0b Address of attack and fade parameters, or ffff if none.
-    *or*
-    08-09 Address of interactive parameters for X-axis,
-          or ffff if not applicable
-    0a-0b Address of interactive parameters for Y-axis,
-         or ffff if not applicable
-
-    0c-0d Delay before execution of effect (little endian encoding, in ms)
-
-
-Time based parameters
----------------------
-
-Attack and fade
-^^^^^^^^^^^^^^^
-
-::
-
-    OP=  02
-    LEN= 08
-    00-01 Address where to store the parameters
-    02-03 Duration of attack (little endian encoding, in ms)
-    04 Level at end of attack. Signed byte.
-    05-06 Duration of fade.
-    07 Level at end of fade.
-
-Magnitude
-^^^^^^^^^
-
-::
-
-    OP=  03
-    LEN= 03
-    00-01 Address
-    02 Level. Signed byte.
-
-Periodicity
-^^^^^^^^^^^
-
-::
-
-    OP=  04
-    LEN= 07
-    00-01 Address
-    02 Magnitude. Signed byte.
-    03 Offset. Signed byte.
-    04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
-    05-06 Period (little endian encoding, in ms)
-
-Interactive parameters
-----------------------
-
-::
-
-    OP=  05
-    LEN= 0a
-    00-01 Address
-    02 Positive Coeff
-    03 Negative Coeff
-    04+05 Offset (center)
-    06+07 Dead band (Val 01F4 = 5000 (decimal))
-    08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal))
-    09 Negative saturation
-
-The encoding is a bit funny here: For coeffs, these are signed values. The
-maximum value is 64 (100 decimal), the min is 9c.
-For the offset, the minimum value is FE0C, the maximum value is 01F4.
-For the deadband, the minimum value is 0, the max is 03E8.
-
-Controls
---------
-
-::
-
-    OP=  41
-    LEN= 03
-    00 Channel
-    01 Start/Stop
-           Val 00: Stop
-           Val 01: Start and play once.
-           Val 41: Start and play n times (See byte 02 below)
-    02 Number of iterations n.
-
-Init
-----
-
-
-Querying features
-^^^^^^^^^^^^^^^^^
-::
-
-    OP=  ff
-    Query command. Length varies according to the query type.
-    The general format of this packet is:
-    ff 01 QUERY [INDEX] CHECKSUM
-    responses are of the same form:
-    FF LEN QUERY VALUE_QUERIED CHECKSUM2
-    where LEN = 1 + length(VALUE_QUERIED)
-
-Query ram size
-~~~~~~~~~~~~~~
-
-::
-
-    QUERY = 42 ('B'uffer size)
-
-The device should reply with the same packet plus two additional bytes
-containing the size of the memory:
-ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
-
-Query number of effects
-~~~~~~~~~~~~~~~~~~~~~~~
-
-::
-
-    QUERY = 4e ('N'umber of effects)
-
-The device should respond by sending the number of effects that can be played
-at the same time (one byte)
-ff 02 4e 14 CS would stand for 20 effects.
-
-Vendor's id
-~~~~~~~~~~~
-
-::
-
-    QUERY = 4d ('M'anufacturer)
-
-Query the vendors'id (2 bytes)
-
-Product id
-~~~~~~~~~~
-
-::
-
-    QUERY = 50 ('P'roduct)
-
-Query the product id (2 bytes)
-
-Open device
-~~~~~~~~~~~
-
-::
-
-    QUERY = 4f ('O'pen)
-
-No data returned.
-
-Close device
-~~~~~~~~~~~~
-
-::
-
-    QUERY = 43 ('C')lose
-
-No data returned.
-
-Query effect
-~~~~~~~~~~~~
-
-::
-
-    QUERY = 45 ('E')
-
-Send effect type.
-Returns nonzero if supported (2 bytes)
-
-Firmware Version
-~~~~~~~~~~~~~~~~
-
-::
-
-    QUERY = 56 ('V'ersion)
-
-Sends back 3 bytes - major, minor, subminor
-
-Initialisation of the device
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Set Control
-~~~~~~~~~~~
-
-.. note::
-    Device dependent, can be different on different models!
-
-::
-
-    OP=  40 <idx> <val> [<val>]
-    LEN= 2 or 3
-    00 Idx
-       Idx 00 Set dead zone (0..2048)
-       Idx 01 Ignore Deadman sensor (0..1)
-       Idx 02 Enable comm watchdog (0..1)
-       Idx 03 Set the strength of the spring (0..100)
-       Idx 04 Enable or disable the spring (0/1)
-       Idx 05 Set axis saturation threshold (0..2048)
-
-Set Effect State
-~~~~~~~~~~~~~~~~
-
-::
-
-    OP=  42 <val>
-    LEN= 1
-    00 State
-       Bit 3 Pause force feedback
-       Bit 2 Enable force feedback
-       Bit 0 Stop all effects
-
-Set overall
-~~~~~~~~~~~
-
-::
-
-    OP=  43 <val>
-    LEN= 1
-    00 Gain
-       Val 00 = 0%
-       Val 40 = 50%
-       Val 80 = 100%
-
-Parameter memory
-----------------
-
-Each device has a certain amount of memory to store parameters of effects.
-The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below
-is the amount of memory apparently needed for every set of parameters:
-
- - period : 0c
- - magnitude : 02
- - attack and fade : 0e
- - interactive : 08
-
-Appendix: How to study the protocol?
-====================================
-
-1. Generate effects using the force editor provided with the DirectX SDK, or
-use Immersion Studio (freely available at their web site in the developer section:
-www.immersion.com)
-2. Start a soft spying RS232 or USB (depending on where you connected your
-joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
-3. Play the effect, and watch what happens on the spy screen.
-
-A few words about ComPortSpy:
-At first glance, this software seems, hum, well... buggy. In fact, data appear with a
-few seconds latency. Personally, I restart it every time I play an effect.
-Remember it's free (as in free beer) and alpha!
-
-URLS
-====
-
-Check http://www.immerse.com for Immersion Studio,
-and http://www.fcoder.com for ComPortSpy.
-
-
-I-Force is trademark of Immersion Corp.
index b25a67198a65e5a1ae86f3502f004c166d296a91..7a3e71c2bd008c864f34d681a4e3ad68b9eaaaef 100644 (file)
@@ -8,42 +8,9 @@ Contents:
    :maxdepth: 2
    :numbered:
 
-   input
-   input-programming
-   event-codes
-   joydev/index
-   multi-touch-protocol
-   gamepad
-   gameport-programming
-   ff
-   notifier
-   userio
-
-Input drivers
-=============
-
-.. toctree::
-   :maxdepth: 2
-   :numbered:
-
-   alps
-   amijoy
-   appletouch
-   atarikbd
-   bcm5974
-   cma3000_d0x
-   cs461x
-   edt-ft5x06
-   elantech
-   iforce-protocol
-   joystick-parport
-   gpio-tilt
-   ntrig
-   rotary-encoder
-   sentelic
-   walkera0701
-   xpad
-   yealink
+   input_uapi
+   input_kapi
+   devices/index
 
 .. only::  subproject and html
 
index 4d3b22222e93e1eea0ca86c52ebcc68ab8584b13..57dbab652cfa2a4f3a9ce66887c15d28d3a3c8c5 100644 (file)
@@ -1,7 +1,4 @@
-~~~~~~~~~~~~~~~~~~~~~~~~~
-Programming input drivers
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
+===============================
 Creating an input device driver
 ===============================
 
diff --git a/Documentation/input/input_kapi.rst b/Documentation/input/input_kapi.rst
new file mode 100644 (file)
index 0000000..41f1b7e
--- /dev/null
@@ -0,0 +1,17 @@
+.. include:: <isonum.txt>
+
+################################
+Linux Input Subsystem kernel API
+################################
+
+.. class:: toc-title
+
+        Table of Contents
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   input-programming
+   gameport-programming
+   notifier
diff --git a/Documentation/input/input_uapi.rst b/Documentation/input/input_uapi.rst
new file mode 100644 (file)
index 0000000..12ef897
--- /dev/null
@@ -0,0 +1,21 @@
+.. include:: <isonum.txt>
+
+###################################
+Linux Input Subsystem userspace API
+###################################
+
+.. class:: toc-title
+
+        Table of Contents
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   input
+   event-codes
+   multi-touch-protocol
+   gamepad
+   ff
+   joydev/index
+   userio
diff --git a/Documentation/input/joystick-parport.rst b/Documentation/input/joystick-parport.rst
deleted file mode 100644 (file)
index cc2ab87..0000000
+++ /dev/null
@@ -1,611 +0,0 @@
-.. include:: <isonum.txt>
-
-.. _joystick-parport:
-
-==============================
-Parallel port Joystick Drivers
-==============================
-
-:Copyright: |copy| 1998-2000 Vojtech Pavlik <vojtech@ucw.cz>
-:Copyright: |copy| 1998 Andree Borrmann <a.borrmann@tu-bs.de>
-
-
-Sponsored by SuSE
-
-Disclaimer
-==========
-
-Any information in this file is provided as-is, without any guarantee that
-it will be true. So, use it at your own risk. The possible damages that can
-happen include burning your parallel port, and/or the sticks and joystick
-and maybe even more. Like when a lightning kills you it is not our problem.
-
-Introduction
-============
-
-The joystick parport drivers are used for joysticks and gamepads not
-originally designed for PCs and other computers Linux runs on. Because of
-that, PCs usually lack the right ports to connect these devices to. Parallel
-port, because of its ability to change single bits at will, and providing
-both output and input bits is the most suitable port on the PC for
-connecting such devices.
-
-Devices supported
-=================
-
-Many console and 8-bit computer gamepads and joysticks are supported. The
-following subsections discuss usage of each.
-
-NES and SNES
-------------
-
-The Nintendo Entertainment System and Super Nintendo Entertainment System
-gamepads are widely available, and easy to get. Also, they are quite easy to
-connect to a PC, and don't need much processing speed (108 us for NES and
-165 us for SNES, compared to about 1000 us for PC gamepads) to communicate
-with them.
-
-All NES and SNES use the same synchronous serial protocol, clocked from
-the computer's side (and thus timing insensitive). To allow up to 5 NES
-and/or SNES gamepads and/or SNES mice connected to the parallel port at once,
-the output lines of the parallel port are shared, while one of 5 available
-input lines is assigned to each gamepad.
-
-This protocol is handled by the gamecon.c driver, so that's the one
-you'll use for NES, SNES gamepads and SNES mice.
-
-The main problem with PC parallel ports is that they don't have +5V power
-source on any of their pins. So, if you want a reliable source of power
-for your pads, use either keyboard or joystick port, and make a pass-through
-cable. You can also pull the power directly from the power supply (the red
-wire is +5V).
-
-If you want to use the parallel port only, you can take the power is from
-some data pin. For most gamepad and parport implementations only one pin is
-needed, and I'd recommend pin 9 for that, the highest data bit. On the other
-hand, if you are not planning to use anything else than NES / SNES on the
-port, anything between and including pin 4 and pin 9 will work::
-
-    (pin 9) -----> Power
-
-Unfortunately, there are pads that need a lot more of power, and parallel
-ports that can't give much current through the data pins. If this is your
-case, you'll need to use diodes (as a prevention of destroying your parallel
-port), and combine the currents of two or more data bits together::
-
-             Diodes
-    (pin 9) ----|>|-------+------> Power
-                       |
-    (pin 8) ----|>|-------+
-                       |
-    (pin 7) ----|>|-------+
-                       |
-    <and so on>         :
-                       |
-    (pin 4) ----|>|-------+
-
-Ground is quite easy. On PC's parallel port the ground is on any of the
-pins from pin 18 to pin 25. So use any pin of these you like for the ground::
-
-    (pin 18) -----> Ground
-
-NES and SNES pads have two input bits, Clock and Latch, which drive the
-serial transfer. These are connected to pins 2 and 3 of the parallel port,
-respectively::
-
-    (pin 2) -----> Clock
-    (pin 3) -----> Latch
-
-And the last thing is the NES / SNES data wire. Only that isn't shared and
-each pad needs its own data pin. The parallel port pins are::
-
-    (pin 10) -----> Pad 1 data
-    (pin 11) -----> Pad 2 data
-    (pin 12) -----> Pad 3 data
-    (pin 13) -----> Pad 4 data
-    (pin 15) -----> Pad 5 data
-
-Note that pin 14 is not used, since it is not an input pin on the parallel
-port.
-
-This is everything you need on the PC's side of the connection, now on to
-the gamepads side. The NES and SNES have different connectors. Also, there
-are quite a lot of NES clones, and because Nintendo used proprietary
-connectors for their machines, the cloners couldn't and used standard D-Cannon
-connectors. Anyway, if you've got a gamepad, and it has buttons A, B, Turbo
-A, Turbo B, Select and Start, and is connected through 5 wires, then it is
-either a NES or NES clone and will work with this connection. SNES gamepads
-also use 5 wires, but have more buttons. They will work as well, of course::
-
-  Pinout for NES gamepads                 Pinout for SNES gamepads and mice
-
-             +----> Power                   +-----------------------\
-             |                            7 | o  o  o  o |  x  x  o  | 1
-   5 +---------+  7                         +-----------------------/
-     | x  x  o   \                            |  |  |  |          |
-     | o  o  o  o |                           |  |  |  |          +-> Ground
-   4 +------------+ 1                         |  |  |  +------------> Data
-       |  |  |  |                             |  |  +---------------> Latch
-       |  |  |  +-> Ground                    |  +------------------> Clock
-       |  |  +----> Clock                     +---------------------> Power
-       |  +-------> Latch
-       +----------> Data
-
-  Pinout for NES clone (db9) gamepads     Pinout for NES clone (db15) gamepads
-
-        +---------> Clock                    +-----------------> Data
-        | +-------> Latch                    |             +---> Ground
-        | | +-----> Data                     |             |
-        | | |                              ___________________
-    _____________                        8 \ o x x x x x x o / 1
-  5 \ x o o o x / 1                         \ o x x o x x o /
-     \ x o x o /                          15 `~~~~~~~~~~~~~' 9
-    9 `~~~~~~~' 6                             |     |     |
-         |   |                                |     |     +----> Clock
-         |   +----> Power                     |     +----------> Latch
-         +--------> Ground                    +----------------> Power
-
-Multisystem joysticks
----------------------
-
-In the era of 8-bit machines, there was something like de-facto standard
-for joystick ports. They were all digital, and all used D-Cannon 9 pin
-connectors (db9). Because of that, a single joystick could be used without
-hassle on Atari (130, 800XE, 800XL, 2600, 7200), Amiga, Commodore C64,
-Amstrad CPC, Sinclair ZX Spectrum and many other machines. That's why these
-joysticks are called "Multisystem".
-
-Now their pinout::
-
-        +---------> Right
-        | +-------> Left
-        | | +-----> Down
-        | | | +---> Up
-        | | | |
-    _____________
-  5 \ x o o o o / 1
-     \ x o x o /
-    9 `~~~~~~~' 6
-         |   |
-         |   +----> Button
-         +--------> Ground
-
-However, as time passed, extensions to this standard developed, and these
-were not compatible with each other::
-
-
-          Atari 130, 800/XL/XE                   MSX
-
-                                           +-----------> Power
-        +---------> Right                  | +---------> Right
-        | +-------> Left                   | | +-------> Left
-        | | +-----> Down                   | | | +-----> Down
-        | | | +---> Up                     | | | | +---> Up
-        | | | |                            | | | | |
-    _____________                        _____________
-  5 \ x o o o o / 1                    5 \ o o o o o / 1
-     \ x o o o /                          \ o o o o /
-    9 `~~~~~~~' 6                        9 `~~~~~~~' 6
-         | | |                              | | | |
-         | | +----> Button                  | | | +----> Button 1
-         | +------> Power                   | | +------> Button 2
-         +--------> Ground                  | +--------> Output 3
-                                            +----------> Ground
-
-          Amstrad CPC                           Commodore C64
-
-                                           +-----------> Analog Y
-        +---------> Right                  | +---------> Right
-        | +-------> Left                   | | +-------> Left
-        | | +-----> Down                   | | | +-----> Down
-        | | | +---> Up                     | | | | +---> Up
-        | | | |                            | | | | |
-    _____________                        _____________
-  5 \ x o o o o / 1                    5 \ o o o o o / 1
-     \ x o o o /                          \ o o o o /
-    9 `~~~~~~~' 6                        9 `~~~~~~~' 6
-         | | |                              | | | |
-         | | +----> Button 1                | | | +----> Button
-         | +------> Button 2                | | +------> Power
-         +--------> Ground                  | +--------> Ground
-                                            +----------> Analog X
-
-          Sinclair Spectrum +2A/+3           Amiga 1200
-
-      +-----------> Up                     +-----------> Button 3
-      | +---------> Fire                   | +---------> Right
-      | |                                  | | +-------> Left
-      | |   +-----> Ground                 | | | +-----> Down
-      | |   |                              | | | | +---> Up
-      | |   |                              | | | | |
-    _____________                        _____________
-  5 \ o o x o x / 1                    5 \ o o o o o / 1
-     \ o o o o /                          \ o o o o /
-    9 `~~~~~~~' 6                        9 `~~~~~~~' 6
-       | | | |                              | | | |
-       | | | +----> Right                   | | | +----> Button 1
-       | | +------> Left                    | | +------> Power
-       | +--------> Ground                  | +--------> Ground
-       +----------> Down                    +----------> Button 2
-
-  And there were many others.
-
-Multisystem joysticks using db9.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For the Multisystem joysticks, and their derivatives, the db9.c driver
-was written. It allows only one joystick / gamepad per parallel port, but
-the interface is easy to build and works with almost anything.
-
-For the basic 1-button Multisystem joystick you connect its wires to the
-parallel port like this::
-
-    (pin  1) -----> Power
-    (pin 18) -----> Ground
-
-    (pin  2) -----> Up
-    (pin  3) -----> Down
-    (pin  4) -----> Left
-    (pin  5) -----> Right
-    (pin  6) -----> Button 1
-
-However, if the joystick is switch based (eg. clicks when you move it),
-you might or might not, depending on your parallel port, need 10 kOhm pullup
-resistors on each of the direction and button signals, like this::
-
-    (pin 2) ------------+------> Up
-              Resistor  |
-    (pin 1) --[10kOhm]--+
-
-Try without, and if it doesn't work, add them. For TTL based joysticks /
-gamepads the pullups are not needed.
-
-For joysticks with two buttons you connect the second button to pin 7 on
-the parallel port::
-
-    (pin 7) -----> Button 2
-
-And that's it.
-
-On a side note, if you have already built a different adapter for use with
-the digital joystick driver 0.8.0.2, this is also supported by the db9.c
-driver, as device type 8. (See section 3.2)
-
-Multisystem joysticks using gamecon.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For some people just one joystick per parallel port is not enough, and/or
-want to use them on one parallel port together with NES/SNES/PSX pads. This is
-possible using the gamecon.c. It supports up to 5 devices of the above types,
-including 1 and 2 buttons Multisystem joysticks.
-
-However, there is nothing for free. To allow more sticks to be used at
-once, you need the sticks to be purely switch based (that is non-TTL), and
-not to need power. Just a plain simple six switches inside. If your
-joystick can do more (eg. turbofire) you'll need to disable it totally first
-if you want to use gamecon.c.
-
-Also, the connection is a bit more complex. You'll need a bunch of diodes,
-and one pullup resistor. First, you connect the Directions and the button
-the same as for db9, however with the diodes between::
-
-                Diodes
-    (pin 2) -----|<|----> Up
-    (pin 3) -----|<|----> Down
-    (pin 4) -----|<|----> Left
-    (pin 5) -----|<|----> Right
-    (pin 6) -----|<|----> Button 1
-
-For two button sticks you also connect the other button::
-
-    (pin 7) -----|<|----> Button 2
-
-And finally, you connect the Ground wire of the joystick, like done in
-this little schematic to Power and Data on the parallel port, as described
-for the NES / SNES pads in section 2.1 of this file - that is, one data pin
-for each joystick. The power source is shared::
-
-    Data    ------------+-----> Ground
-              Resistor  |
-    Power   --[10kOhm]--+
-
-And that's all, here we go!
-
-Multisystem joysticks using turbografx.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The TurboGraFX interface, designed by
-
-       Steffen Schwenke <schwenke@burg-halle.de>
-
-allows up to 7 Multisystem joysticks connected to the parallel port. In
-Steffen's version, there is support for up to 5 buttons per joystick.  However,
-since this doesn't work reliably on all parallel ports, the turbografx.c driver
-supports only one button per joystick. For more information on how to build the
-interface, see:
-
-       http://www2.burg-halle.de/~schwenke/parport.html
-
-Sony Playstation
-----------------
-
-The PSX controller is supported by the gamecon.c. Pinout of the PSX
-controller (compatible with DirectPadPro)::
-
-    +---------+---------+---------+
-  9 | o  o  o | o  o  o | o  o  o | 1               parallel
-     \________|_________|________/                  port pins
-      |  |      |  |  |   |
-      |  |      |  |  |   +-------->  Clock    ---  (4)
-      |  |      |  |  +------------>  Select   ---  (3)
-      |  |      |  +--------------->  Power    ---  (5-9)
-      |  |      +------------------>  Ground   ---  (18-25)
-      |  +------------------------->  Command  ---  (2)
-      +---------------------------->  Data     ---  (one of 10,11,12,13,15)
-
-The driver supports these controllers:
-
- * Standard PSX Pad
- * NegCon PSX Pad
- * Analog PSX Pad (red mode)
- * Analog PSX Pad (green mode)
- * PSX Rumble Pad
- * PSX DDR Pad
-
-Sega
-----
-
-All the Sega controllers are more or less based on the standard 2-button
-Multisystem joystick. However, since they don't use switches and use TTL
-logic, the only driver usable with them is the db9.c driver.
-
-Sega Master System
-~~~~~~~~~~~~~~~~~~
-
-The SMS gamepads are almost exactly the same as normal 2-button
-Multisystem joysticks. Set the driver to Multi2 mode, use the corresponding
-parallel port pins, and the following schematic::
-
-      +-----------> Power
-      | +---------> Right
-      | | +-------> Left
-      | | | +-----> Down
-      | | | | +---> Up
-      | | | | |
-    _____________
-  5 \ o o o o o / 1
-     \ o o x o /
-    9 `~~~~~~~' 6
-       | |   |
-       | |   +----> Button 1
-       | +--------> Ground
-       +----------> Button 2
-
-Sega Genesis aka MegaDrive
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The Sega Genesis (in Europe sold as Sega MegaDrive) pads are an extension
-to the Sega Master System pads. They use more buttons (3+1, 5+1, 6+1).  Use
-the following schematic::
-
-        +-----------> Power
-        | +---------> Right
-        | | +-------> Left
-        | | | +-----> Down
-        | | | | +---> Up
-        | | | | |
-      _____________
-    5 \ o o o o o / 1
-       \ o o o o /
-      9 `~~~~~~~' 6
-        | | | |
-        | | | +----> Button 1
-        | | +------> Select
-        | +--------> Ground
-        +----------> Button 2
-
-The Select pin goes to pin 14 on the parallel port::
-
-    (pin 14) -----> Select
-
-The rest is the same as for Multi2 joysticks using db9.c
-
-Sega Saturn
-~~~~~~~~~~~
-
-Sega Saturn has eight buttons, and to transfer that, without hacks like
-Genesis 6 pads use, it needs one more select pin. Anyway, it is still
-handled by the db9.c driver. Its pinout is very different from anything
-else.  Use this schematic::
-
-      +-----------> Select 1
-      | +---------> Power
-      | | +-------> Up
-      | | | +-----> Down
-      | | | | +---> Ground
-      | | | | |
-    _____________
-  5 \ o o o o o / 1
-     \ o o o o /
-    9 `~~~~~~~' 6
-       | | | |
-       | | | +----> Select 2
-       | | +------> Right
-       | +--------> Left
-       +----------> Power
-
-Select 1 is pin 14 on the parallel port, Select 2 is pin 16 on the
-parallel port::
-
-    (pin 14) -----> Select 1
-    (pin 16) -----> Select 2
-
-The other pins (Up, Down, Right, Left, Power, Ground) are the same as for
-Multi joysticks using db9.c
-
-Amiga CD32
-----------
-
-Amiga CD32 joypad uses the following pinout::
-
-        +-----------> Button 3
-        | +---------> Right
-        | | +-------> Left
-        | | | +-----> Down
-        | | | | +---> Up
-        | | | | |
-      _____________
-    5 \ o o o o o / 1
-       \ o o o o /
-      9 `~~~~~~~' 6
-        | | | |
-        | | | +----> Button 1
-        | | +------> Power
-        | +--------> Ground
-        +----------> Button 2
-
-It can be connected to the parallel port and driven by db9.c driver. It needs the following wiring:
-
-       ============    =============
-       CD32 pad        Parallel port
-       ============    =============
-       1 (Up)           2 (D0)
-       2 (Down)         3 (D1)
-       3 (Left)         4 (D2)
-       4 (Right)        5 (D3)
-       5 (Button 3)    14 (AUTOFD)
-       6 (Button 1)    17 (SELIN)
-       7 (+5V)          1 (STROBE)
-       8 (Gnd)         18 (Gnd)
-       9 (Button 2)     7 (D5)
-       ============    =============
-
-The drivers
-===========
-
-There are three drivers for the parallel port interfaces. Each, as
-described above, allows to connect a different group of joysticks and pads.
-Here are described their command lines:
-
-gamecon.c
----------
-
-Using gamecon.c you can connect up to five devices to one parallel port. It
-uses the following kernel/module command line::
-
-       gamecon.map=port,pad1,pad2,pad3,pad4,pad5
-
-Where ``port`` the number of the parport interface (eg. 0 for parport0).
-
-And ``pad1`` to ``pad5`` are pad types connected to different data input pins
-(10,11,12,13,15), as described in section 2.1 of this file.
-
-The types are:
-
-       ===== =============================
-       Type  Joystick/Pad
-       ===== =============================
-         0   None
-         1   SNES pad
-         2   NES pad
-         4   Multisystem 1-button joystick
-         5   Multisystem 2-button joystick
-         6   N64 pad
-         7   Sony PSX controller
-         8   Sony PSX DDR controller
-         9   SNES mouse
-       ===== =============================
-
-The exact type of the PSX controller type is autoprobed when used, so
-hot swapping should work (but is not recommended).
-
-Should you want to use more than one of parallel ports at once, you can use
-gamecon.map2 and gamecon.map3 as additional command line parameters for two
-more parallel ports.
-
-There are two options specific to PSX driver portion.  gamecon.psx_delay sets
-the command delay when talking to the controllers. The default of 25 should
-work but you can try lowering it for better performance. If your pads don't
-respond try raising it until they work. Setting the type to 8 allows the
-driver to be used with Dance Dance Revolution or similar games. Arrow keys are
-registered as key presses instead of X and Y axes.
-
-db9.c
------
-
-Apart from making an interface, there is nothing difficult on using the
-db9.c driver. It uses the following kernel/module command line::
-
-       db9.dev=port,type
-
-Where ``port`` is the number of the parport interface (eg. 0 for parport0).
-
-Caveat here: This driver only works on bidirectional parallel ports. If
-your parallel port is recent enough, you should have no trouble with this.
-Old parallel ports may not have this feature.
-
-``Type`` is the type of joystick or pad attached:
-
-       ===== ======================================================
-       Type  Joystick/Pad
-       ===== ======================================================
-         0   None
-         1   Multisystem 1-button joystick
-         2   Multisystem 2-button joystick
-         3   Genesis pad (3+1 buttons)
-         5   Genesis pad (5+1 buttons)
-         6   Genesis pad (6+2 buttons)
-         7   Saturn pad (8 buttons)
-         8   Multisystem 1-button joystick (v0.8.0.2 pin-out)
-         9   Two Multisystem 1-button joysticks (v0.8.0.2 pin-out)
-        10   Amiga CD32 pad
-       ===== ======================================================
-
-Should you want to use more than one of these joysticks/pads at once, you
-can use db9.dev2 and db9.dev3 as additional command line parameters for two
-more joysticks/pads.
-
-turbografx.c
-------------
-
-The turbografx.c driver uses a very simple kernel/module command line::
-
-       turbografx.map=port,js1,js2,js3,js4,js5,js6,js7
-
-Where ``port`` is the number of the parport interface (eg. 0 for parport0).
-
-``jsX`` is the number of buttons the Multisystem joysticks connected to the
-interface ports 1-7 have. For a standard multisystem joystick, this is 1.
-
-Should you want to use more than one of these interfaces at once, you can
-use turbografx.map2 and turbografx.map3 as additional command line parameters
-for two more interfaces.
-
-PC parallel port pinout
-=======================
-
-::
-
-                 .----------------------------------------.
-   At the PC:     \ 13 12 11 10  9  8  7  6  5  4  3  2  1 /
-                   \  25 24 23 22 21 20 19 18 17 16 15 14 /
-                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-======  =======  =============
-   Pin  Name     Description
-======  =======  =============
-     1  /STROBE  Strobe
-   2-9  D0-D7    Data Bit 0-7
-    10  /ACK     Acknowledge
-    11  BUSY     Busy
-    12  PE       Paper End
-    13  SELIN    Select In
-    14  /AUTOFD  Autofeed
-    15  /ERROR   Error
-    16  /INIT    Initialize
-    17  /SEL     Select
- 18-25  GND      Signal Ground
-======  =======  =============
-
-
-That's all, folks! Have fun!
diff --git a/Documentation/input/ntrig.rst b/Documentation/input/ntrig.rst
deleted file mode 100644 (file)
index a6b22ce..0000000
+++ /dev/null
@@ -1,137 +0,0 @@
-.. include:: <isonum.txt>
-
-=========================
-N-Trig touchscreen Driver
-=========================
-
-:Copyright: |copy| 2008-2010 Rafi Rubin <rafi@seas.upenn.edu>
-:Copyright: |copy| 2009-2010 Stephane Chatty
-
-This driver provides support for N-Trig pen and multi-touch sensors.  Single
-and multi-touch events are translated to the appropriate protocols for
-the hid and input systems.  Pen events are sufficiently hid compliant and
-are left to the hid core.  The driver also provides additional filtering
-and utility functions accessible with sysfs and module parameters.
-
-This driver has been reported to work properly with multiple N-Trig devices
-attached.
-
-
-Parameters
-----------
-
-Note: values set at load time are global and will apply to all applicable
-devices.  Adjusting parameters with sysfs will override the load time values,
-but only for that one device.
-
-The following parameters are used to configure filters to reduce noise:
-
-+-----------------------+-----------------------------------------------------+
-|activate_slack                |number of fingers to ignore before processing events |
-+-----------------------+-----------------------------------------------------+
-|activation_height,    |size threshold to activate immediately               |
-|activation_width      |                                                     |
-+-----------------------+-----------------------------------------------------+
-|min_height,           |size threshold bellow which fingers are ignored      |
-|min_width             |both to decide activation and during activity        |
-+-----------------------+-----------------------------------------------------+
-|deactivate_slack      |the number of "no contact" frames to ignore before   |
-|                      |propagating the end of activity events               |
-+-----------------------+-----------------------------------------------------+
-
-When the last finger is removed from the device, it sends a number of empty
-frames.  By holding off on deactivation for a few frames we can tolerate false
-erroneous disconnects, where the sensor may mistakenly not detect a finger that
-is still present.  Thus deactivate_slack addresses problems where a users might
-see breaks in lines during drawing, or drop an object during a long drag.
-
-
-Additional sysfs items
-----------------------
-
-These nodes just provide easy access to the ranges reported by the device.
-
-+-----------------------+-----------------------------------------------------+
-|sensor_logical_height, | the range for positions reported during activity    |
-|sensor_logical_width   |                                                     |
-+-----------------------+-----------------------------------------------------+
-|sensor_physical_height,| internal ranges not used for normal events but      |
-|sensor_physical_width  | useful for tuning                                   |
-+-----------------------+-----------------------------------------------------+
-
-All N-Trig devices with product id of 1 report events in the ranges of
-
-* X: 0-9600
-* Y: 0-7200
-
-However not all of these devices have the same physical dimensions.  Most
-seem to be 12" sensors (Dell Latitude XT and XT2 and the HP TX2), and
-at least one model (Dell Studio 17) has a 17" sensor.  The ratio of physical
-to logical sizes is used to adjust the size based filter parameters.
-
-
-Filtering
----------
-
-With the release of the early multi-touch firmwares it became increasingly
-obvious that these sensors were prone to erroneous events.  Users reported
-seeing both inappropriately dropped contact and ghosts, contacts reported
-where no finger was actually touching the screen.
-
-Deactivation slack helps prevent dropped contact for single touch use, but does
-not address the problem of dropping one of more contacts while other contacts
-are still active.  Drops in the multi-touch context require additional
-processing and should be handled in tandem with tacking.
-
-As observed ghost contacts are similar to actual use of the sensor, but they
-seem to have different profiles.  Ghost activity typically shows up as small
-short lived touches.  As such, I assume that the longer the continuous stream
-of events the more likely those events are from a real contact, and that the
-larger the size of each contact the more likely it is real.  Balancing the
-goals of preventing ghosts and accepting real events quickly (to minimize
-user observable latency), the filter accumulates confidence for incoming
-events until it hits thresholds and begins propagating.  In the interest in
-minimizing stored state as well as the cost of operations to make a decision,
-I've kept that decision simple.
-
-Time is measured in terms of the number of fingers reported, not frames since
-the probability of multiple simultaneous ghosts is expected to drop off
-dramatically with increasing numbers.  Rather than accumulate weight as a
-function of size, I just use it as a binary threshold.  A sufficiently large
-contact immediately overrides the waiting period and leads to activation.
-
-Setting the activation size thresholds to large values will result in deciding
-primarily on activation slack.  If you see longer lived ghosts, turning up the
-activation slack while reducing the size thresholds may suffice to eliminate
-the ghosts while keeping the screen quite responsive to firm taps.
-
-Contacts continue to be filtered with min_height and min_width even after
-the initial activation filter is satisfied.  The intent is to provide
-a mechanism for filtering out ghosts in the form of an extra finger while
-you actually are using the screen.  In practice this sort of ghost has
-been far less problematic or relatively rare and I've left the defaults
-set to 0 for both parameters, effectively turning off that filter.
-
-I don't know what the optimal values are for these filters.  If the defaults
-don't work for you, please play with the parameters.  If you do find other
-values more comfortable, I would appreciate feedback.
-
-The calibration of these devices does drift over time.  If ghosts or contact
-dropping worsen and interfere with the normal usage of your device, try
-recalibrating it.
-
-
-Calibration
------------
-
-The N-Trig windows tools provide calibration and testing routines.  Also an
-unofficial unsupported set of user space tools including a calibrator is
-available at:
-http://code.launchpad.net/~rafi-seas/+junk/ntrig_calib
-
-
-Tracking
---------
-
-As of yet, all tested N-Trig firmwares do not track fingers.  When multiple
-contacts are active they seem to be sorted primarily by Y position.
diff --git a/Documentation/input/rotary-encoder.rst b/Documentation/input/rotary-encoder.rst
deleted file mode 100644 (file)
index b07b20a..0000000
+++ /dev/null
@@ -1,131 +0,0 @@
-============================================================
-rotary-encoder - a generic driver for GPIO connected devices
-============================================================
-
-:Author: Daniel Mack <daniel@caiaq.de>, Feb 2009
-
-Function
---------
-
-Rotary encoders are devices which are connected to the CPU or other
-peripherals with two wires. The outputs are phase-shifted by 90 degrees
-and by triggering on falling and rising edges, the turn direction can
-be determined.
-
-Some encoders have both outputs low in stable states, others also have
-a stable state with both outputs high (half-period mode) and some have
-a stable state in all steps (quarter-period mode).
-
-The phase diagram of these two outputs look like this::
-
-                  _____       _____       _____
-                 |     |     |     |     |     |
-  Channel A  ____|     |_____|     |_____|     |____
-
-                 :  :  :  :  :  :  :  :  :  :  :  :
-            __       _____       _____       _____
-              |     |     |     |     |     |     |
-  Channel B   |_____|     |_____|     |_____|     |__
-
-                 :  :  :  :  :  :  :  :  :  :  :  :
-  Event          a  b  c  d  a  b  c  d  a  b  c  d
-
-                |<-------->|
-                 one step
-
-                |<-->|
-                 one step (half-period mode)
-
-                |<>|
-                 one step (quarter-period mode)
-
-For more information, please see
-       https://en.wikipedia.org/wiki/Rotary_encoder
-
-
-Events / state machine
-----------------------
-
-In half-period mode, state a) and c) above are used to determine the
-rotational direction based on the last stable state. Events are reported in
-states b) and d) given that the new stable state is different from the last
-(i.e. the rotation was not reversed half-way).
-
-Otherwise, the following apply:
-
-a) Rising edge on channel A, channel B in low state
-       This state is used to recognize a clockwise turn
-
-b) Rising edge on channel B, channel A in high state
-       When entering this state, the encoder is put into 'armed' state,
-       meaning that there it has seen half the way of a one-step transition.
-
-c) Falling edge on channel A, channel B in high state
-       This state is used to recognize a counter-clockwise turn
-
-d) Falling edge on channel B, channel A in low state
-       Parking position. If the encoder enters this state, a full transition
-       should have happened, unless it flipped back on half the way. The
-       'armed' state tells us about that.
-
-Platform requirements
----------------------
-
-As there is no hardware dependent call in this driver, the platform it is
-used with must support gpiolib. Another requirement is that IRQs must be
-able to fire on both edges.
-
-
-Board integration
------------------
-
-To use this driver in your system, register a platform_device with the
-name 'rotary-encoder' and associate the IRQs and some specific platform
-data with it. Because the driver uses generic device properties, this can
-be done either via device tree, ACPI, or using static board files, like in
-example below:
-
-::
-
-       /* board support file example */
-
-       #include <linux/input.h>
-       #include <linux/gpio/machine.h>
-       #include <linux/property.h>
-
-       #define GPIO_ROTARY_A 1
-       #define GPIO_ROTARY_B 2
-
-       static struct gpiod_lookup_table rotary_encoder_gpios = {
-               .dev_id = "rotary-encoder.0",
-               .table = {
-                       GPIO_LOOKUP_IDX("gpio-0",
-                                       GPIO_ROTARY_A, NULL, 0, GPIO_ACTIVE_LOW),
-                       GPIO_LOOKUP_IDX("gpio-0",
-                                       GPIO_ROTARY_B, NULL, 1, GPIO_ACTIVE_HIGH),
-                       { },
-               },
-       };
-
-       static const struct property_entry rotary_encoder_properties[] __initconst = {
-               PROPERTY_ENTRY_INTEGER("rotary-encoder,steps-per-period", u32, 24),
-               PROPERTY_ENTRY_INTEGER("linux,axis",                      u32, ABS_X),
-               PROPERTY_ENTRY_INTEGER("rotary-encoder,relative_axis",    u32, 0),
-               { },
-       };
-
-       static struct platform_device rotary_encoder_device = {
-               .name           = "rotary-encoder",
-               .id             = 0,
-       };
-
-       ...
-
-       gpiod_add_lookup_table(&rotary_encoder_gpios);
-       device_add_properties(&rotary_encoder_device, rotary_encoder_properties);
-       platform_device_register(&rotary_encoder_device);
-
-       ...
-
-Please consult device tree binding documentation to see all properties
-supported by the driver.
diff --git a/Documentation/input/sentelic.rst b/Documentation/input/sentelic.rst
deleted file mode 100644 (file)
index d1a476f..0000000
+++ /dev/null
@@ -1,901 +0,0 @@
-.. include:: <isonum.txt>
-
-===============
-Sentelic Driver
-===============
-
-
-:Copyright: |copy| 2002-2011 Sentelic Corporation.
-
-:Last update: Dec-07-2011
-
-Finger Sensing Pad Intellimouse Mode(scrolling wheel, 4th and 5th buttons)
-==========================================================================
-
-A) MSID 4: Scrolling wheel mode plus Forward page(4th button) and Backward
-   page (5th button)
-
-1. Set sample rate to 200;
-2. Set sample rate to 200;
-3. Set sample rate to 80;
-4. Issuing the "Get device ID" command (0xF2) and waits for the response;
-5. FSP will respond 0x04.
-
-::
-
-    Packet 1
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |Y|X|y|x|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 | | |B|F|W|W|W|W|
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    Byte 1: Bit7 => Y overflow
-           Bit6 => X overflow
-           Bit5 => Y sign bit
-           Bit4 => X sign bit
-           Bit3 => 1
-           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-    Byte 2: X Movement(9-bit 2's complement integers)
-    Byte 3: Y Movement(9-bit 2's complement integers)
-    Byte 4: Bit3~Bit0 => the scrolling wheel's movement since the last data report.
-                       valid values, -8 ~ +7
-           Bit4 => 1 = 4th mouse button is pressed, Forward one page.
-                   0 = 4th mouse button is not pressed.
-           Bit5 => 1 = 5th mouse button is pressed, Backward one page.
-                   0 = 5th mouse button is not pressed.
-
-B) MSID 6: Horizontal and Vertical scrolling
-
-- Set bit 1 in register 0x40 to 1
-
-FSP replaces scrolling wheel's movement as 4 bits to show horizontal and
-vertical scrolling.
-
-::
-
-    Packet 1
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |Y|X|y|x|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 | | |B|F|r|l|u|d|
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    Byte 1: Bit7 => Y overflow
-           Bit6 => X overflow
-           Bit5 => Y sign bit
-           Bit4 => X sign bit
-           Bit3 => 1
-           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-    Byte 2: X Movement(9-bit 2's complement integers)
-    Byte 3: Y Movement(9-bit 2's complement integers)
-    Byte 4: Bit0 => the Vertical scrolling movement downward.
-           Bit1 => the Vertical scrolling movement upward.
-           Bit2 => the Horizontal scrolling movement leftward.
-           Bit3 => the Horizontal scrolling movement rightward.
-           Bit4 => 1 = 4th mouse button is pressed, Forward one page.
-                   0 = 4th mouse button is not pressed.
-           Bit5 => 1 = 5th mouse button is pressed, Backward one page.
-                   0 = 5th mouse button is not pressed.
-
-C) MSID 7
-
-FSP uses 2 packets (8 Bytes) to represent Absolute Position.
-so we have PACKET NUMBER to identify packets.
-
-  If PACKET NUMBER is 0, the packet is Packet 1.
-  If PACKET NUMBER is 1, the packet is Packet 2.
-  Please count this number in program.
-
-MSID6 special packet will be enable at the same time when enable MSID 7.
-
-Absolute position for STL3886-G0
-================================
-
-1. Set bit 2 or 3 in register 0x40 to 1
-2. Set bit 6 in register 0x40 to 1
-
-::
-
-    Packet 1 (ABSOLUTE POSITION)
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |0|1|V|1|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|d|u|X|X|Y|Y|
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    Byte 1: Bit7~Bit6 => 00, Normal data packet
-                   => 01, Absolute coordination packet
-                   => 10, Notify packet
-           Bit5 => valid bit
-           Bit4 => 1
-           Bit3 => 1
-           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-    Byte 2: X coordinate (xpos[9:2])
-    Byte 3: Y coordinate (ypos[9:2])
-    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-           Bit3~Bit2 => X coordinate (ypos[1:0])
-           Bit4 => scroll up
-           Bit5 => scroll down
-           Bit6 => scroll left
-           Bit7 => scroll right
-
-    Notify Packet for G0
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |1|0|0|1|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |M|M|M|M|M|M|M|M|  4 |0|0|0|0|0|0|0|0|
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    Byte 1: Bit7~Bit6 => 00, Normal data packet
-                   => 01, Absolute coordination packet
-                   => 10, Notify packet
-           Bit5 => 0
-           Bit4 => 1
-           Bit3 => 1
-           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-    Byte 2: Message Type => 0x5A (Enable/Disable status packet)
-           Mode Type => 0xA5 (Normal/Icon mode status)
-    Byte 3: Message Type => 0x00 (Disabled)
-                       => 0x01 (Enabled)
-           Mode Type    => 0x00 (Normal)
-                       => 0x01 (Icon)
-    Byte 4: Bit7~Bit0 => Don't Care
-
-Absolute position for STL3888-Ax
-================================
-
-::
-
-    Packet 1 (ABSOLUTE POSITION)
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |0|1|V|A|1|L|0|1|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |x|x|y|y|X|X|Y|Y|
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    Byte 1: Bit7~Bit6 => 00, Normal data packet
-                   => 01, Absolute coordination packet
-                   => 10, Notify packet
-                   => 11, Normal data packet with on-pad click
-           Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
-                   When both fingers are up, the last two reports have zero valid
-                   bit.
-           Bit4 => arc
-           Bit3 => 1
-           Bit2 => Left Button, 1 is pressed, 0 is released.
-           Bit1 => 0
-           Bit0 => 1
-    Byte 2: X coordinate (xpos[9:2])
-    Byte 3: Y coordinate (ypos[9:2])
-    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-           Bit3~Bit2 => X coordinate (ypos[1:0])
-           Bit5~Bit4 => y1_g
-           Bit7~Bit6 => x1_g
-
-    Packet 2 (ABSOLUTE POSITION)
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |0|1|V|A|1|R|1|0|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |x|x|y|y|X|X|Y|Y|
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    Byte 1: Bit7~Bit6 => 00, Normal data packet
-                   => 01, Absolute coordinates packet
-                   => 10, Notify packet
-                   => 11, Normal data packet with on-pad click
-           Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
-                   When both fingers are up, the last two reports have zero valid
-                   bit.
-           Bit4 => arc
-           Bit3 => 1
-           Bit2 => Right Button, 1 is pressed, 0 is released.
-           Bit1 => 1
-           Bit0 => 0
-    Byte 2: X coordinate (xpos[9:2])
-    Byte 3: Y coordinate (ypos[9:2])
-    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-           Bit3~Bit2 => X coordinate (ypos[1:0])
-           Bit5~Bit4 => y2_g
-           Bit7~Bit6 => x2_g
-
-    Notify Packet for STL3888-Ax
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |1|0|1|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|d|u|0|0|0|0|
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    Byte 1: Bit7~Bit6 => 00, Normal data packet
-                   => 01, Absolute coordinates packet
-                   => 10, Notify packet
-                   => 11, Normal data packet with on-pad click
-           Bit5 => 1
-           Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1):
-                   0: left button is generated by the on-pad command
-                   1: left button is generated by the external button
-           Bit3 => 1
-           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-    Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode)
-    Byte 3: Bit7~Bit6 => Don't care
-           Bit5~Bit4 => Number of fingers
-           Bit3~Bit1 => Reserved
-           Bit0 => 1: enter gesture mode; 0: leaving gesture mode
-    Byte 4: Bit7 => scroll right button
-           Bit6 => scroll left button
-           Bit5 => scroll down button
-           Bit4 => scroll up button
-               * Note that if gesture and additional button (Bit4~Bit7)
-               happen at the same time, the button information will not
-               be sent.
-           Bit3~Bit0 => Reserved
-
-Sample sequence of Multi-finger, Multi-coordinate mode:
-
-       notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1,
-       abs pkt 2, ..., notify packet (valid bit == 0)
-
-Absolute position for STL3888-B0
-================================
-
-::
-
-    Packet 1(ABSOLUTE POSITION)
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |0|1|V|F|1|0|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|u|d|X|X|Y|Y|
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    Byte 1: Bit7~Bit6 => 00, Normal data packet
-                   => 01, Absolute coordinates packet
-                   => 10, Notify packet
-                   => 11, Normal data packet with on-pad click
-           Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
-                   When both fingers are up, the last two reports have zero valid
-                   bit.
-           Bit4 => finger up/down information. 1: finger down, 0: finger up.
-           Bit3 => 1
-           Bit2 => finger index, 0 is the first finger, 1 is the second finger.
-           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-    Byte 2: X coordinate (xpos[9:2])
-    Byte 3: Y coordinate (ypos[9:2])
-    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-           Bit3~Bit2 => X coordinate (ypos[1:0])
-           Bit4 => scroll down button
-           Bit5 => scroll up button
-           Bit6 => scroll left button
-           Bit7 => scroll right button
-
-    Packet 2 (ABSOLUTE POSITION)
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |0|1|V|F|1|1|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|u|d|X|X|Y|Y|
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    Byte 1: Bit7~Bit6 => 00, Normal data packet
-                   => 01, Absolute coordination packet
-                   => 10, Notify packet
-                   => 11, Normal data packet with on-pad click
-           Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
-                   When both fingers are up, the last two reports have zero valid
-                   bit.
-           Bit4 => finger up/down information. 1: finger down, 0: finger up.
-           Bit3 => 1
-           Bit2 => finger index, 0 is the first finger, 1 is the second finger.
-           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-    Byte 2: X coordinate (xpos[9:2])
-    Byte 3: Y coordinate (ypos[9:2])
-    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-           Bit3~Bit2 => X coordinate (ypos[1:0])
-           Bit4 => scroll down button
-           Bit5 => scroll up button
-           Bit6 => scroll left button
-           Bit7 => scroll right button
-
-Notify Packet for STL3888-B0::
-
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |1|0|1|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|u|d|0|0|0|0|
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    Byte 1: Bit7~Bit6 => 00, Normal data packet
-                   => 01, Absolute coordination packet
-                   => 10, Notify packet
-                   => 11, Normal data packet with on-pad click
-           Bit5 => 1
-           Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1):
-                   0: left button is generated by the on-pad command
-                   1: left button is generated by the external button
-           Bit3 => 1
-           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-    Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode)
-    Byte 3: Bit7~Bit6 => Don't care
-           Bit5~Bit4 => Number of fingers
-           Bit3~Bit1 => Reserved
-           Bit0 => 1: enter gesture mode; 0: leaving gesture mode
-    Byte 4: Bit7 => scroll right button
-           Bit6 => scroll left button
-           Bit5 => scroll up button
-           Bit4 => scroll down button
-               * Note that if gesture and additional button(Bit4~Bit7)
-               happen at the same time, the button information will not
-               be sent.
-           Bit3~Bit0 => Reserved
-
-Sample sequence of Multi-finger, Multi-coordinate mode:
-
-       notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1,
-       abs pkt 2, ..., notify packet (valid bit == 0)
-
-Absolute position for STL3888-Cx and STL3888-Dx
-===============================================
-
-::
-
-    Single Finger, Absolute Coordinate Mode (SFAC)
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |0|1|0|P|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|B|F|X|X|Y|Y|
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    Byte 1: Bit7~Bit6 => 00, Normal data packet
-                   => 01, Absolute coordinates packet
-                   => 10, Notify packet
-           Bit5 => Coordinate mode(always 0 in SFAC mode):
-                   0: single-finger absolute coordinates (SFAC) mode
-                   1: multi-finger, multiple coordinates (MFMC) mode
-           Bit4 => 0: The LEFT button is generated by on-pad command (OPC)
-                   1: The LEFT button is generated by external button
-                   Default is 1 even if the LEFT button is not pressed.
-           Bit3 => Always 1, as specified by PS/2 protocol.
-           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-    Byte 2: X coordinate (xpos[9:2])
-    Byte 3: Y coordinate (ypos[9:2])
-    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-           Bit3~Bit2 => X coordinate (ypos[1:0])
-           Bit4 => 4th mouse button(forward one page)
-           Bit5 => 5th mouse button(backward one page)
-           Bit6 => scroll left button
-           Bit7 => scroll right button
-
-    Multi Finger, Multiple Coordinates Mode (MFMC):
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |0|1|1|P|1|F|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|B|F|X|X|Y|Y|
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    Byte 1: Bit7~Bit6 => 00, Normal data packet
-                   => 01, Absolute coordination packet
-                   => 10, Notify packet
-           Bit5 => Coordinate mode (always 1 in MFMC mode):
-                   0: single-finger absolute coordinates (SFAC) mode
-                   1: multi-finger, multiple coordinates (MFMC) mode
-           Bit4 => 0: The LEFT button is generated by on-pad command (OPC)
-                   1: The LEFT button is generated by external button
-                   Default is 1 even if the LEFT button is not pressed.
-           Bit3 => Always 1, as specified by PS/2 protocol.
-           Bit2 => Finger index, 0 is the first finger, 1 is the second finger.
-                   If bit 1 and 0 are all 1 and bit 4 is 0, the middle external
-                   button is pressed.
-           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-    Byte 2: X coordinate (xpos[9:2])
-    Byte 3: Y coordinate (ypos[9:2])
-    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-           Bit3~Bit2 => X coordinate (ypos[1:0])
-           Bit4 => 4th mouse button(forward one page)
-           Bit5 => 5th mouse button(backward one page)
-           Bit6 => scroll left button
-           Bit7 => scroll right button
-
-When one of the two fingers is up, the device will output four consecutive
-MFMC#0 report packets with zero X and Y to represent 1st finger is up or
-four consecutive MFMC#1 report packets with zero X and Y to represent that
-the 2nd finger is up.  On the other hand, if both fingers are up, the device
-will output four consecutive single-finger, absolute coordinate(SFAC) packets
-with zero X and Y.
-
-Notify Packet for STL3888-Cx/Dx::
-
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |1|0|0|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|u|d|0|0|0|0|
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    Byte 1: Bit7~Bit6 => 00, Normal data packet
-                   => 01, Absolute coordinates packet
-                   => 10, Notify packet
-           Bit5 => Always 0
-           Bit4 => 0: The LEFT button is generated by on-pad command(OPC)
-                   1: The LEFT button is generated by external button
-                   Default is 1 even if the LEFT button is not pressed.
-           Bit3 => 1
-           Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-           Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-           Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-    Byte 2: Message type:
-           0xba => gesture information
-           0xc0 => one finger hold-rotating gesture
-    Byte 3: The first parameter for the received message:
-           0xba => gesture ID (refer to the 'Gesture ID' section)
-           0xc0 => region ID
-    Byte 4: The second parameter for the received message:
-           0xba => N/A
-           0xc0 => finger up/down information
-
-Sample sequence of Multi-finger, Multi-coordinates mode:
-
-       notify packet (valid bit == 1), MFMC packet 1 (byte 1, bit 2 == 0),
-       MFMC packet 2 (byte 1, bit 2 == 1), MFMC packet 1, MFMC packet 2,
-       ..., notify packet (valid bit == 0)
-
-       That is, when the device is in MFMC mode, the host will receive
-       interleaved absolute coordinate packets for each finger.
-
-FSP Enable/Disable packet
-=========================
-
-::
-
-    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-      1   |Y|X|0|0|1|M|R|L|  2  |0|1|0|1|1|0|1|E|  3 | | | | | | | | |  4 | | | | | | | | |
-         |---------------|     |---------------|    |---------------|    |---------------|
-
-    FSP will send out enable/disable packet when FSP receive PS/2 enable/disable
-    command. Host will receive the packet which Middle, Right, Left button will
-    be set. The packet only use byte 0 and byte 1 as a pattern of original packet.
-    Ignore the other bytes of the packet.
-
-    Byte 1: Bit7 => 0, Y overflow
-           Bit6 => 0, X overflow
-           Bit5 => 0, Y sign bit
-           Bit4 => 0, X sign bit
-           Bit3 => 1
-           Bit2 => 1, Middle Button
-           Bit1 => 1, Right Button
-           Bit0 => 1, Left Button
-    Byte 2: Bit7~1 => (0101101b)
-           Bit0 => 1 = Enable
-                   0 = Disable
-    Byte 3: Don't care
-    Byte 4: Don't care (MOUSE ID 3, 4)
-    Byte 5~8: Don't care (Absolute packet)
-
-PS/2 Command Set
-================
-
-FSP supports basic PS/2 commanding set and modes, refer to following URL for
-details about PS/2 commands:
-
-http://www.computer-engineering.org/ps2mouse/
-
-Programming Sequence for Determining Packet Parsing Flow
-========================================================
-
-1. Identify FSP by reading device ID(0x00) and version(0x01) register
-
-2. For FSP version < STL3888 Cx, determine number of buttons by reading
-   the 'test mode status' (0x20) register::
-
-       buttons = reg[0x20] & 0x30
-
-       if buttons == 0x30 or buttons == 0x20:
-               # two/four buttons
-               Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse'
-               section A for packet parsing detail(ignore byte 4, bit ~ 7)
-       elif buttons == 0x10:
-               # 6 buttons
-               Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse'
-               section B for packet parsing detail
-       elif buttons == 0x00:
-               # 6 buttons
-               Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse'
-               section A for packet parsing detail
-
-3. For FSP version >= STL3888 Cx:
-       Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse'
-       section A for packet parsing detail (ignore byte 4, bit ~ 7)
-
-Programming Sequence for Register Reading/Writing
-=================================================
-
-Register inversion requirement:
-
-Following values needed to be inverted(the '~' operator in C) before being
-sent to FSP::
-
-       0xe8, 0xe9, 0xee, 0xf2, 0xf3 and 0xff.
-
-Register swapping requirement:
-
-Following values needed to have their higher 4 bits and lower 4 bits being
-swapped before being sent to FSP::
-
-       10, 20, 40, 60, 80, 100 and 200.
-
-Register reading sequence:
-
-       1. send 0xf3 PS/2 command to FSP;
-
-       2. send 0x66 PS/2 command to FSP;
-
-       3. send 0x88 PS/2 command to FSP;
-
-       4. send 0xf3 PS/2 command to FSP;
-
-       5. if the register address being to read is not required to be
-       inverted(refer to the 'Register inversion requirement' section),
-       goto step 6
-
-         a. send 0x68 PS/2 command to FSP;
-
-         b. send the inverted register address to FSP and goto step 8;
-
-       6. if the register address being to read is not required to be
-       swapped(refer to the 'Register swapping requirement' section),
-       goto step 7
-
-         a. send 0xcc PS/2 command to FSP;
-
-         b. send the swapped register address to FSP and goto step 8;
-
-       7. send 0x66 PS/2 command to FSP;
-
-         a. send the original register address to FSP and goto step 8;
-
-       8. send 0xe9(status request) PS/2 command to FSP;
-
-       9. the 4th byte of the response read from FSP should be the
-       requested register value(?? indicates don't care byte)::
-
-               host: 0xe9
-               3888: 0xfa (??) (??) (val)
-
-       * Note that since the Cx release, the hardware will return 1's
-         complement of the register value at the 3rd byte of status request
-         result::
-
-               host: 0xe9
-               3888: 0xfa (??) (~val) (val)
-
-Register writing sequence:
-
-       1. send 0xf3 PS/2 command to FSP;
-
-       2. if the register address being to write is not required to be
-       inverted(refer to the 'Register inversion requirement' section),
-       goto step 3
-
-         a. send 0x74 PS/2 command to FSP;
-
-         b. send the inverted register address to FSP and goto step 5;
-
-       3. if the register address being to write is not required to be
-       swapped(refer to the 'Register swapping requirement' section),
-       goto step 4
-
-         a. send 0x77 PS/2 command to FSP;
-
-         b. send the swapped register address to FSP and goto step 5;
-
-       4. send 0x55 PS/2 command to FSP;
-
-         a. send the register address to FSP and goto step 5;
-
-       5. send 0xf3 PS/2 command to FSP;
-
-       6. if the register value being to write is not required to be
-       inverted(refer to the 'Register inversion requirement' section),
-       goto step 7
-
-         a. send 0x47 PS/2 command to FSP;
-
-         b. send the inverted register value to FSP and goto step 9;
-
-       7. if the register value being to write is not required to be
-       swapped(refer to the 'Register swapping requirement' section),
-       goto step 8
-
-         a. send 0x44 PS/2 command to FSP;
-
-         b. send the swapped register value to FSP and goto step 9;
-
-       8. send 0x33 PS/2 command to FSP;
-
-         a. send the register value to FSP;
-
-       9. the register writing sequence is completed.
-
-       * Since the Cx release, the hardware will return 1's
-         complement of the register value at the 3rd byte of status request
-         result. Host can optionally send another 0xe9 (status request) PS/2
-         command to FSP at the end of register writing to verify that the
-         register writing operation is successful (?? indicates don't care
-         byte)::
-
-               host: 0xe9
-               3888: 0xfa (??) (~val) (val)
-
-Programming Sequence for Page Register Reading/Writing
-======================================================
-
-In order to overcome the limitation of maximum number of registers
-supported, the hardware separates register into different groups called
-'pages.' Each page is able to include up to 255 registers.
-
-The default page after power up is 0x82; therefore, if one has to get
-access to register 0x8301, one has to use following sequence to switch
-to page 0x83, then start reading/writing from/to offset 0x01 by using
-the register read/write sequence described in previous section.
-
-Page register reading sequence:
-
-       1. send 0xf3 PS/2 command to FSP;
-
-       2. send 0x66 PS/2 command to FSP;
-
-       3. send 0x88 PS/2 command to FSP;
-
-       4. send 0xf3 PS/2 command to FSP;
-
-       5. send 0x83 PS/2 command to FSP;
-
-       6. send 0x88 PS/2 command to FSP;
-
-       7. send 0xe9(status request) PS/2 command to FSP;
-
-       8. the response read from FSP should be the requested page value.
-
-
-Page register writing sequence:
-
-       1. send 0xf3 PS/2 command to FSP;
-
-       2. send 0x38 PS/2 command to FSP;
-
-       3. send 0x88 PS/2 command to FSP;
-
-       4. send 0xf3 PS/2 command to FSP;
-
-       5. if the page address being written is not required to be
-       inverted(refer to the 'Register inversion requirement' section),
-       goto step 6
-
-         a. send 0x47 PS/2 command to FSP;
-
-         b. send the inverted page address to FSP and goto step 9;
-
-       6. if the page address being written is not required to be
-       swapped(refer to the 'Register swapping requirement' section),
-       goto step 7
-
-         a. send 0x44 PS/2 command to FSP;
-
-         b. send the swapped page address to FSP and goto step 9;
-
-       7. send 0x33 PS/2 command to FSP;
-
-       8. send the page address to FSP;
-
-       9. the page register writing sequence is completed.
-
-Gesture ID
-==========
-
-Unlike other devices which sends multiple fingers' coordinates to host,
-FSP processes multiple fingers' coordinates internally and convert them
-into a 8 bits integer, namely 'Gesture ID.'  Following is a list of
-supported gesture IDs:
-
-       ======= ==================================
-       ID      Description
-       ======= ==================================
-       0x86    2 finger straight up
-       0x82    2 finger straight down
-       0x80    2 finger straight right
-       0x84    2 finger straight left
-       0x8f    2 finger zoom in
-       0x8b    2 finger zoom out
-       0xc0    2 finger curve, counter clockwise
-       0xc4    2 finger curve, clockwise
-       0x2e    3 finger straight up
-       0x2a    3 finger straight down
-       0x28    3 finger straight right
-       0x2c    3 finger straight left
-       0x38    palm
-       ======= ==================================
-
-Register Listing
-================
-
-Registers are represented in 16 bits values. The higher 8 bits represent
-the page address and the lower 8 bits represent the relative offset within
-that particular page.  Refer to the 'Programming Sequence for Page Register
-Reading/Writing' section for instructions on how to change current page
-address::
-
- offset        width           default r/w     name
- 0x8200        bit7~bit0       0x01    RO      device ID
-
- 0x8201        bit7~bit0               RW      version ID
-                                       0xc1: STL3888 Ax
-                                       0xd0 ~ 0xd2: STL3888 Bx
-                                       0xe0 ~ 0xe1: STL3888 Cx
-                                       0xe2 ~ 0xe3: STL3888 Dx
-
- 0x8202        bit7~bit0       0x01    RO      vendor ID
-
- 0x8203        bit7~bit0       0x01    RO      product ID
-
- 0x8204        bit3~bit0       0x01    RW      revision ID
-
- 0x820b                                        test mode status 1
-       bit3            1       RO      0: rotate 180 degree
-                                       1: no rotation
-                                       *only supported by H/W prior to Cx
-
- 0x820f                                        register file page control
-       bit2            0       RW      1: rotate 180 degree
-                                       0: no rotation
-                                       *supported since Cx
-
-       bit0            0       RW      1 to enable page 1 register files
-                                       *only supported by H/W prior to Cx
-
- 0x8210                                RW      system control 1
-       bit0            1       RW      Reserved, must be 1
-       bit1            0       RW      Reserved, must be 0
-       bit4            0       RW      Reserved, must be 0
-       bit5            1       RW      register clock gating enable
-                                       0: read only, 1: read/write enable
-       (Note that following registers does not require clock gating being
-       enabled prior to write: 05 06 07 08 09 0c 0f 10 11 12 16 17 18 23 2e
-       40 41 42 43.  In addition to that, this bit must be 1 when gesture
-       mode is enabled)
-
- 0x8220                                        test mode status
-       bit5~bit4               RO      number of buttons
-                                       11 => 2, lbtn/rbtn
-                                       10 => 4, lbtn/rbtn/scru/scrd
-                                       01 => 6, lbtn/rbtn/scru/scrd/scrl/scrr
-                                       00 => 6, lbtn/rbtn/scru/scrd/fbtn/bbtn
-                                       *only supported by H/W prior to Cx
-
- 0x8231                                RW      on-pad command detection
-       bit7            0       RW      on-pad command left button down tag
-                                       enable
-                                       0: disable, 1: enable
-                                       *only supported by H/W prior to Cx
-
- 0x8234                                RW      on-pad command control 5
-       bit4~bit0       0x05    RW      XLO in 0s/4/1, so 03h = 0010.1b = 2.5
-       (Note that position unit is in 0.5 scanline)
-                                       *only supported by H/W prior to Cx
-
-       bit7            0       RW      on-pad tap zone enable
-                                       0: disable, 1: enable
-                                       *only supported by H/W prior to Cx
-
- 0x8235                                RW      on-pad command control 6
-       bit4~bit0       0x1d    RW      XHI in 0s/4/1, so 19h = 1100.1b = 12.5
-       (Note that position unit is in 0.5 scanline)
-                                       *only supported by H/W prior to Cx
-
- 0x8236                                RW      on-pad command control 7
-       bit4~bit0       0x04    RW      YLO in 0s/4/1, so 03h = 0010.1b = 2.5
-       (Note that position unit is in 0.5 scanline)
-                                       *only supported by H/W prior to Cx
-
- 0x8237                                RW      on-pad command control 8
-       bit4~bit0       0x13    RW      YHI in 0s/4/1, so 11h = 1000.1b = 8.5
-       (Note that position unit is in 0.5 scanline)
-                                       *only supported by H/W prior to Cx
-
- 0x8240                                RW      system control 5
-       bit1            0       RW      FSP Intellimouse mode enable
-                                       0: disable, 1: enable
-                                       *only supported by H/W prior to Cx
-
-       bit2            0       RW      movement + abs. coordinate mode enable
-                                       0: disable, 1: enable
-       (Note that this function has the functionality of bit 1 even when
-       bit 1 is not set. However, the format is different from that of bit 1.
-       In addition, when bit 1 and bit 2 are set at the same time, bit 2 will
-       override bit 1.)
-                                       *only supported by H/W prior to Cx
-
-       bit3            0       RW      abs. coordinate only mode enable
-                                       0: disable, 1: enable
-       (Note that this function has the functionality of bit 1 even when
-       bit 1 is not set. However, the format is different from that of bit 1.
-       In addition, when bit 1, bit 2 and bit 3 are set at the same time,
-       bit 3 will override bit 1 and 2.)
-                                       *only supported by H/W prior to Cx
-
-       bit5            0       RW      auto switch enable
-                                       0: disable, 1: enable
-                                       *only supported by H/W prior to Cx
-
-       bit6            0       RW      G0 abs. + notify packet format enable
-                                       0: disable, 1: enable
-       (Note that the absolute/relative coordinate output still depends on
-       bit 2 and 3.  That is, if any of those bit is 1, host will receive
-       absolute coordinates; otherwise, host only receives packets with
-       relative coordinate.)
-                                       *only supported by H/W prior to Cx
-
-       bit7            0       RW      EN_PS2_F2: PS/2 gesture mode 2nd
-                                       finger packet enable
-                                       0: disable, 1: enable
-                                       *only supported by H/W prior to Cx
-
- 0x8243                                RW      on-pad control
-       bit0            0       RW      on-pad control enable
-                                       0: disable, 1: enable
-       (Note that if this bit is cleared, bit 3/5 will be ineffective)
-                                       *only supported by H/W prior to Cx
-
-       bit3            0       RW      on-pad fix vertical scrolling enable
-                                       0: disable, 1: enable
-                                       *only supported by H/W prior to Cx
-
-       bit5            0       RW      on-pad fix horizontal scrolling enable
-                                       0: disable, 1: enable
-                                       *only supported by H/W prior to Cx
-
- 0x8290                                RW      software control register 1
-       bit0            0       RW      absolute coordination mode
-                                       0: disable, 1: enable
-                                       *supported since Cx
-
-       bit1            0       RW      gesture ID output
-                                       0: disable, 1: enable
-                                       *supported since Cx
-
-       bit2            0       RW      two fingers' coordinates output
-                                       0: disable, 1: enable
-                                       *supported since Cx
-
-       bit3            0       RW      finger up one packet output
-                                       0: disable, 1: enable
-                                       *supported since Cx
-
-       bit4            0       RW      absolute coordination continuous mode
-                                       0: disable, 1: enable
-                                       *supported since Cx
-
-       bit6~bit5       00      RW      gesture group selection
-                                       00: basic
-                                       01: suite
-                                       10: suite pro
-                                       11: advanced
-                                       *supported since Cx
-
-       bit7            0       RW      Bx packet output compatible mode
-                                       0: disable, 1: enable
-                                       *supported since Cx
-                                       *supported since Cx
-
-
- 0x833d                                RW      on-pad command control 1
-       bit7            1       RW      on-pad command detection enable
-                                       0: disable, 1: enable
-                                       *supported since Cx
-
- 0x833e                                RW      on-pad command detection
-       bit7            0       RW      on-pad command left button down tag
-                                       enable. Works only in H/W based PS/2
-                                       data packet mode.
-                                       0: disable, 1: enable
-                                       *supported since Cx
diff --git a/Documentation/input/walkera0701.rst b/Documentation/input/walkera0701.rst
deleted file mode 100644 (file)
index 2adda99..0000000
+++ /dev/null
@@ -1,128 +0,0 @@
-===========================
-Walkera WK-0701 transmitter
-===========================
-
-Walkera WK-0701 transmitter is supplied with a ready to fly Walkera
-helicopters such as HM36, HM37, HM60. The walkera0701 module enables to use
-this transmitter as joystick
-
-Devel homepage and download:
-http://zub.fei.tuke.sk/walkera-wk0701/
-
-or use cogito:
-cg-clone http://zub.fei.tuke.sk/GIT/walkera0701-joystick
-
-
-Connecting to PC
-================
-
-At back side of transmitter S-video connector can be found. Modulation
-pulses from processor to HF part can be found at pin 2 of this connector,
-pin 3 is GND. Between pin 3 and CPU 5k6 resistor can be found. To get
-modulation pulses to PC, signal pulses must be amplified.
-
-Cable: (walkera TX to parport)
-
-Walkera WK-0701 TX S-VIDEO connector::
-
- (back side of TX)
-     __   __              S-video:                                  canon25
-    /  |_|  \             pin 2 (signal)              NPN           parport
-   / O 4 3 O \            pin 3 (GND)        LED        ________________  10 ACK
-  ( O 2   1 O )                                         | C
-   \   ___   /      2 ________________________|\|_____|/
-    | [___] |                                 |/|   B |\
-     -------        3 __________________________________|________________ 25 GND
-                                                          E
-
-I use green LED and BC109 NPN transistor.
-
-Software
-========
-
-Build kernel with walkera0701 module. Module walkera0701 need exclusive
-access to parport, modules like lp must be unloaded before loading
-walkera0701 module, check dmesg for error messages. Connect TX to PC by
-cable and run jstest /dev/input/js0 to see values from TX. If no value can
-be changed by TX "joystick", check output from /proc/interrupts. Value for
-(usually irq7) parport must increase if TX is on.
-
-
-
-Technical details
-=================
-
-Driver use interrupt from parport ACK input bit to measure pulse length
-using hrtimers.
-
-Frame format:
-Based on walkera WK-0701 PCM Format description by Shaul Eizikovich.
-(downloaded from http://www.smartpropoplus.com/Docs/Walkera_Wk-0701_PCM.pdf)
-
-Signal pulses
--------------
-
-::
-
-                     (ANALOG)
-      SYNC      BIN   OCT
-    +---------+      +------+
-    |         |      |      |
-  --+         +------+      +---
-
-Frame
------
-
-::
-
- SYNC , BIN1, OCT1, BIN2, OCT2 ... BIN24, OCT24, BIN25, next frame SYNC ..
-
-pulse length
-------------
-
-::
-
-   Binary values:              Analog octal values:
-
-   288 uS Binary 0             318 uS       000
-   438 uS Binary 1             398 uS       001
-                               478 uS       010
-                               558 uS       011
-                               638 uS       100
-  1306 uS SYNC                 718 uS       101
-                               798 uS       110
-                               878 uS       111
-
-24 bin+oct values + 1 bin value = 24*4+1 bits  = 97 bits
-
-(Warning, pulses on ACK are inverted by transistor, irq is raised up on sync
-to bin change or octal value to bin change).
-
-Binary data representations
----------------------------
-
-One binary and octal value can be grouped to nibble. 24 nibbles + one binary
-values can be sampled between sync pulses.
-
-Values for first four channels (analog joystick values) can be found in
-first 10 nibbles. Analog value is represented by one sign bit and 9 bit
-absolute binary value. (10 bits per channel). Next nibble is checksum for
-first ten nibbles.
-
-Next nibbles 12 .. 21 represents four channels (not all channels can be
-directly controlled from TX). Binary representations are the same as in first
-four channels. In nibbles 22 and 23 is a special magic number. Nibble 24 is
-checksum for nibbles 12..23.
-
-After last octal value for nibble 24 and next sync pulse one additional
-binary value can be sampled. This bit and magic number is not used in
-software driver. Some details about this magic numbers can be found in
-Walkera_Wk-0701_PCM.pdf.
-
-Checksum calculation
---------------------
-
-Summary of octal values in nibbles must be same as octal value in checksum
-nibble (only first 3 bits are used). Binary value for checksum nibble is
-calculated by sum of binary values in checked nibbles + sum of octal values
-in checked nibbles divided by 8. Only bit 0 of this sum is used.
diff --git a/Documentation/input/xpad.rst b/Documentation/input/xpad.rst
deleted file mode 100644 (file)
index 0bae002..0000000
+++ /dev/null
@@ -1,242 +0,0 @@
-=======================================================
-xpad - Linux USB driver for Xbox compatible controllers
-=======================================================
-
-This driver exposes all first-party and third-party Xbox compatible
-controllers. It has a long history and has enjoyed considerable usage
-as Window's xinput library caused most PC games to focus on Xbox
-controller compatibility.
-
-Due to backwards compatibility all buttons are reported as digital.
-This only effects Original Xbox controllers. All later controller models
-have only digital face buttons.
-
-Rumble is supported on some models of Xbox 360 controllers but not of
-Original Xbox controllers nor on Xbox One controllers. As of writing
-the Xbox One's rumble protocol has not been reverse engineered but in
-the future could be supported.
-
-
-Notes
-=====
-
-The number of buttons/axes reported varies based on 3 things:
-
-- if you are using a known controller
-- if you are using a known dance pad
-- if using an unknown device (one not listed below), what you set in the
-  module configuration for "Map D-PAD to buttons rather than axes for unknown
-  pads" (module option dpad_to_buttons)
-
-If you set dpad_to_buttons to N and you are using an unknown device
-the driver will map the directional pad to axes (X/Y).
-If you said Y it will map the d-pad to buttons, which is needed for dance
-style games to function correctly. The default is Y.
-
-dpad_to_buttons has no effect for known pads. A erroneous commit message
-claimed dpad_to_buttons could be used to force behavior on known devices.
-This is not true. Both dpad_to_buttons and triggers_to_buttons only affect
-unknown controllers.
-
-
-Normal Controllers
-------------------
-
-With a normal controller, the directional pad is mapped to its own X/Y axes.
-The jstest-program from joystick-1.2.15 (jstest-version 2.1.0) will report 8
-axes and 10 buttons.
-
-All 8 axes work, though they all have the same range (-32768..32767)
-and the zero-setting is not correct for the triggers (I don't know if that
-is some limitation of jstest, since the input device setup should be fine. I
-didn't have a look at jstest itself yet).
-
-All of the 10 buttons work (in digital mode). The six buttons on the
-right side (A, B, X, Y, black, white) are said to be "analog" and
-report their values as 8 bit unsigned, not sure what this is good for.
-
-I tested the controller with quake3, and configuration and
-in game functionality were OK. However, I find it rather difficult to
-play first person shooters with a pad. Your mileage may vary.
-
-
-Xbox Dance Pads
----------------
-
-When using a known dance pad, jstest will report 6 axes and 14 buttons.
-
-For dance style pads (like the redoctane pad) several changes
-have been made.  The old driver would map the d-pad to axes, resulting
-in the driver being unable to report when the user was pressing both
-left+right or up+down, making DDR style games unplayable.
-
-Known dance pads automatically map the d-pad to buttons and will work
-correctly out of the box.
-
-If your dance pad is recognized by the driver but is using axes instead
-of buttons, see section 0.3 - Unknown Controllers
-
-I've tested this with Stepmania, and it works quite well.
-
-
-Unknown Controllers
--------------------
-
-If you have an unknown xbox controller, it should work just fine with
-the default settings.
-
-HOWEVER if you have an unknown dance pad not listed below, it will not
-work UNLESS you set "dpad_to_buttons" to 1 in the module configuration.
-
-PLEASE, if you have an unknown controller, email Dom <binary1230@yahoo.com> with
-a dump from /proc/bus/usb and a description of the pad (manufacturer, country,
-whether it is a dance pad or normal controller) so that we can add your pad
-to the list of supported devices, ensuring that it will work out of the
-box in the future.
-
-
-USB adapters
-============
-
-All generations of Xbox controllers speak USB over the wire.
-
-- Original Xbox controllers use a proprietary connector and require adapters.
-- Wireless Xbox 360 controllers require a 'Xbox 360 Wireless Gaming Receiver
-  for Windows'
-- Wired Xbox 360 controllers use standard USB connectors.
-- Xbox One controllers can be wireless but speak Wi-Fi Direct and are not
-  yet supported.
-- Xbox One controllers can be wired and use standard Micro-USB connectors.
-
-
-
-Original Xbox USB adapters
---------------------------
-
-Using this driver with an Original Xbox controller requires an
-adapter cable to break out the proprietary connector's pins to USB.
-You can buy these online fairly cheap, or build your own.
-
-Such a cable is pretty easy to build. The Controller itself is a USB
-compound device (a hub with three ports for two expansion slots and
-the controller device) with the only difference in a nonstandard connector
-(5 pins vs. 4 on standard USB 1.0 connectors).
-
-You just need to solder a USB connector onto the cable and keep the
-yellow wire unconnected. The other pins have the same order on both
-connectors so there is no magic to it. Detailed info on these matters
-can be found on the net ([1], [2], [3]).
-
-Thanks to the trip splitter found on the cable you don't even need to cut the
-original one. You can buy an extension cable and cut that instead. That way,
-you can still use the controller with your X-Box, if you have one ;)
-
-
-
-Driver Installation
-===================
-
-Once you have the adapter cable, if needed, and the controller connected
-the xpad module should be auto loaded. To confirm you can cat
-/proc/bus/usb/devices. There should be an entry like the one at the end [4].
-
-
-
-Supported Controllers
-=====================
-
-For a full list of supported controllers and associated vendor and product
-IDs see the xpad_device[] array[6].
-
-As of the historic version 0.0.6 (2006-10-10) the following devices
-were supported::
-
- original Microsoft XBOX controller (US),    vendor=0x045e, product=0x0202
- smaller  Microsoft XBOX controller (US),    vendor=0x045e, product=0x0289
- original Microsoft XBOX controller (Japan), vendor=0x045e, product=0x0285
- InterAct PowerPad Pro (Germany),            vendor=0x05fd, product=0x107a
- RedOctane Xbox Dance Pad (US),              vendor=0x0c12, product=0x8809
-
-Unrecognized models of Xbox controllers should function as Generic
-Xbox controllers. Unrecognized Dance Pad controllers require setting
-the module option 'dpad_to_buttons'.
-
-If you have an unrecognized controller please see 0.3 - Unknown Controllers
-
-
-Manual Testing
-==============
-
-To test this driver's functionality you may use 'jstest'.
-
-For example::
-
-    > modprobe xpad
-    > modprobe joydev
-    > jstest /dev/js0
-
-If you're using a normal controller, there should be a single line showing
-18 inputs (8 axes, 10 buttons), and its values should change if you move
-the sticks and push the buttons.  If you're using a dance pad, it should
-show 20 inputs (6 axes, 14 buttons).
-
-It works? Voila, you're done ;)
-
-
-
-Thanks
-======
-
-I have to thank ITO Takayuki for the detailed info on his site
-    http://euc.jp/periphs/xbox-controller.ja.html.
-
-His useful info and both the usb-skeleton as well as the iforce input driver
-(Greg Kroah-Hartmann; Vojtech Pavlik) helped a lot in rapid prototyping
-the basic functionality.
-
-
-
-References
-==========
-
-[1]: http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
-
-[2]: http://xpad.xbox-scene.com/
-
-[3]: http://www.markosweb.com/www/xboxhackz.com/
-
-[4]: /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany)::
-
-    T:  Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#=  5 Spd=12  MxCh= 0
-    D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs=  1
-    P:  Vendor=05fd ProdID=107a Rev= 1.00
-    C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
-    I:  If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none)
-    E:  Ad=81(I) Atr=03(Int.) MxPS=  32 Ivl= 10ms
-    E:  Ad=02(O) Atr=03(Int.) MxPS=  32 Ivl= 10ms
-
-[5]: /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US)::
-
-    T:  Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12  MxCh= 0
-    D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
-    P:  Vendor=0c12 ProdID=8809 Rev= 0.01
-    S:  Product=XBOX DDR
-    C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
-    I:  If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad
-    E:  Ad=82(I) Atr=03(Int.) MxPS=  32 Ivl=4ms
-    E:  Ad=02(O) Atr=03(Int.) MxPS=  32 Ivl=4ms
-
-[6]: http://lxr.free-electrons.com/ident?i=xpad_device
-
-
-
-Historic Edits
-==============
-
-2002-07-16 - Marko Friedemann <mfr@bmx-chemnitz.de>
- - original doc
-
-2005-03-19 - Dominic Cerquetti <binary1230@yahoo.com>
- - added stuff for dance pads, new d-pad->axes mappings
-
-Later changes may be viewed with 'git log Documentation/input/xpad.txt'
diff --git a/Documentation/input/yealink.rst b/Documentation/input/yealink.rst
deleted file mode 100644 (file)
index b231d8b..0000000
+++ /dev/null
@@ -1,238 +0,0 @@
-===============================================
-Driver documentation for yealink usb-p1k phones
-===============================================
-
-Status
-======
-
-The p1k is a relatively cheap usb 1.1 phone with:
-
-  - keyboard           full support, yealink.ko / input event API
-  - LCD                        full support, yealink.ko / sysfs API
-  - LED                        full support, yealink.ko / sysfs API
-  - dialtone           full support, yealink.ko / sysfs API
-  - ringtone           full support, yealink.ko / sysfs API
-  - audio playback     full support, snd_usb_audio.ko / alsa API
-  - audio record       full support, snd_usb_audio.ko / alsa API
-
-For vendor documentation see http://www.yealink.com
-
-
-Compilation (stand alone version)
-=================================
-
-Currently only kernel 2.6.x.y versions are supported.
-In order to build the yealink.ko module do::
-
-  make
-
-If you encounter problems please check if in the MAKE_OPTS variable in
-the Makefile is pointing to the location where your kernel sources
-are located, default /usr/src/linux.
-
-
-Troubleshooting
-~~~~~~~~~~~~~~~
-
-:Q: Module yealink compiled and installed without any problem but phone
-    is not initialized and does not react to any actions.
-:A: If you see something like:
-    hiddev0: USB HID v1.00 Device [Yealink Network Technology Ltd. VOIP USB Phone
-    in dmesg, it means that the hid driver has grabbed the device first. Try to
-    load module yealink before any other usb hid driver. Please see the
-    instructions provided by your distribution on module configuration.
-
-:Q: Phone is working now (displays version and accepts keypad input) but I can't
-    find the sysfs files.
-:A: The sysfs files are located on the particular usb endpoint. On most
-    distributions you can do: "find /sys/ -name get_icons" for a hint.
-
-
-keyboard features
-=================
-
-The current mapping in the kernel is provided by the map_p1k_to_key
-function::
-
-   Physical USB-P1K button layout      input events
-
-
-              up                            up
-        IN           OUT               left,   right
-             down                          down
-
-      pickup   C    hangup             enter, backspace, escape
-        1      2      3                        1, 2, 3
-        4      5      6                        4, 5, 6,
-        7      8      9                        7, 8, 9,
-        *      0      #                        *, 0, #,
-
-The "up" and "down" keys, are symbolised by arrows on the button.
-The "pickup" and "hangup" keys are symbolised by a green and red phone
-on the button.
-
-
-LCD features
-============
-
-The LCD is divided and organised as a 3 line display::
-
-    |[]   [][]   [][]   [][]   in   |[][]
-    |[] M [][] D [][] : [][]   out  |[][]
-                              store
-
-    NEW REP         SU MO TU WE TH FR SA
-
-    [] [] [] [] [] [] [] [] [] [] [] []
-    [] [] [] [] [] [] [] [] [] [] [] []
-
-
-  Line 1  Format (see below)   : 18.e8.M8.88...188
-         Icon names            :   M  D  :  IN OUT STORE
-  Line 2  Format               : .........
-         Icon name             : NEW REP SU MO TU WE TH FR SA
-  Line 3  Format               : 888888888888
-
-
-Format description:
-  From a userspace perspective the world is separated into "digits" and "icons".
-  A digit can have a character set, an icon can only be ON or OFF.
-
-  Format specifier::
-
-    '8' :  Generic 7 segment digit with individual addressable segments
-
-    Reduced capability 7 segment digit, when segments are hard wired together.
-    '1' : 2 segments digit only able to produce a 1.
-    'e' : Most significant day of the month digit,
-          able to produce at least 1 2 3.
-    'M' : Most significant minute digit,
-          able to produce at least 0 1 2 3 4 5.
-
-    Icons or pictograms:
-    '.' : For example like AM, PM, SU, a 'dot' .. or other single segment
-         elements.
-
-
-Driver usage
-============
-
-For userland the following interfaces are available using the sysfs interface::
-
-  /sys/.../
-           line1       Read/Write, lcd line1
-           line2       Read/Write, lcd line2
-           line3       Read/Write, lcd line3
-
-          get_icons    Read, returns a set of available icons.
-          hide_icon    Write, hide the element by writing the icon name.
-          show_icon    Write, display the element by writing the icon name.
-
-          map_seg7     Read/Write, the 7 segments char set, common for all
-                       yealink phones. (see map_to_7segment.h)
-
-          ringtone     Write, upload binary representation of a ringtone,
-                       see yealink.c. status EXPERIMENTAL due to potential
-                       races between async. and sync usb calls.
-
-
-lineX
-~~~~~
-
-Reading /sys/../lineX will return the format string with its current value.
-
-  Example::
-
-    cat ./line3
-    888888888888
-    Linux Rocks!
-
-Writing to /sys/../lineX will set the corresponding LCD line.
-
- - Excess characters are ignored.
- - If less characters are written than allowed, the remaining digits are
-   unchanged.
- - The tab '\t'and '\n' char does not overwrite the original content.
- - Writing a space to an icon will always hide its content.
-
-  Example::
-
-    date +"%m.%e.%k:%M"  | sed 's/^0/ /' > ./line1
-
-  Will update the LCD with the current date & time.
-
-
-get_icons
-~~~~~~~~~
-
-Reading will return all available icon names and its current settings::
-
-  cat ./get_icons
-  on M
-  on D
-  on :
-     IN
-     OUT
-     STORE
-     NEW
-     REP
-     SU
-     MO
-     TU
-     WE
-     TH
-     FR
-     SA
-     LED
-     DIALTONE
-     RINGTONE
-
-
-show/hide icons
-~~~~~~~~~~~~~~~
-
-Writing to these files will update the state of the icon.
-Only one icon at a time can be updated.
-
-If an icon is also on a ./lineX the corresponding value is
-updated with the first letter of the icon.
-
-  Example - light up the store icon::
-
-    echo -n "STORE" > ./show_icon
-
-    cat ./line1
-    18.e8.M8.88...188
-                 S
-
-  Example - sound the ringtone for 10 seconds::
-
-    echo -n RINGTONE > /sys/..../show_icon
-    sleep 10
-    echo -n RINGTONE > /sys/..../hide_icon
-
-
-Sound features
-==============
-
-Sound is supported by the ALSA driver: snd_usb_audio
-
-One 16-bit channel with sample and playback rates of 8000 Hz is the practical
-limit of the device.
-
-  Example - recording test::
-
-    arecord -v -d 10 -r 8000 -f S16_LE -t wav  foobar.wav
-
-  Example - playback test::
-
-    aplay foobar.wav
-
-
-Credits & Acknowledgments
-=========================
-
-  - Olivier Vandorpe, for starting the usbb2k-api project doing much of
-    the reverse engineering.
-  - Martin Diehl, for pointing out how to handle USB memory allocation.
-  - Dmitry Torokhov, for the numerous code reviews and suggestions.