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

Pull input subsystem updates from Dmitry Torokhov:

 - a big update from Mauro converting input documentation to ReST format

 - Synaptics PS/2 is now aware of SMBus companion devices, which means
   that we can now use native RMI4 protocol to handle touchpads, instead
   of relying on legacy PS/2 mode.

 - we removed support from BMA180 accelerometer from input devices as it
   is now handled properly by IIO

 - update to TSC2007 to corretcly report pressure

 - other miscellaneous driver fixes.

* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input: (152 commits)
  Input: ar1021_i2c - use BIT to check for a bit
  Input: twl4030-pwrbutton - use input_set_capability() helper
  Input: twl4030-pwrbutton - use correct device for irq request
  Input: ar1021_i2c - enable touch mode during open
  Input: add uinput documentation
  dt-bindings: input: add bindings document for ar1021_i2c driver
  dt-bindings: input: rotary-encoder: fix typo
  Input: xen-kbdfront - add module parameter for setting resolution
  ARM: pxa/raumfeld: fix compile error in rotary controller resources
  Input: xpad - do not suggest writing to Dominic
  Input: xpad - don't use literal blocks inside footnotes
  Input: xpad - note that usb/devices is now at /sys/kernel/debug/
  Input: docs - freshen up introduction
  Input: docs - split input docs into kernel- and user-facing
  Input: docs - note that MT-A protocol is obsolete
  Input: docs - update joystick documentation a bit
  Input: docs - remove disclaimer/GPL notice
  Input: fix "Game console" heading level in joystick documentation
  Input: rotary-encoder - remove references to platform data from docs
  Input: move documentation for Amiga CD32
  ...

Documentation/conf.py

@@ -348,6 +348,8 @@ latex_documents = [
      'The kernel development community', 'manual'),
     ('driver-api/index', 'driver-api.tex', 'The kernel driver API manual',
      'The kernel development community', 'manual'),
+    ('input/index', 'linux-input.tex', 'The Linux input driver subsystem',
+     'The kernel development community', 'manual'),
     ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation',
      'The kernel development community', 'manual'),
     ('process/index', 'development-process.tex', 'Linux Kernel Development Documentation',

Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt

@@ -24,6 +24,8 @@ Optional Properties:
 - debounce-delay-ms:	debounce interval in milliseconds
 - col-scan-delay-us:	delay, measured in microseconds, that is needed
 			before we can scan keypad after activating column gpio
+- drive-inactive-cols:	drive inactive columns during scan,
+			default is to turn inactive columns into inputs.
 
 Example:
 	matrix-keypad {

Documentation/devicetree/bindings/input/pwm-beeper.txt

@@ -8,6 +8,7 @@ Required properties:
 
 Optional properties:
 - amp-supply: phandle to a regulator that acts as an amplifier for the beeper
+- beeper-hz:  bell frequency in Hz
 
 Example:
 

Documentation/devicetree/bindings/input/qcom,pm8xxx-vib.txt

@@ -7,6 +7,7 @@ PROPERTIES
 	Value type: <string>
 	Definition: must be one of:
 		    "qcom,pm8058-vib"
+		    "qcom,pm8916-vib"
 		    "qcom,pm8921-vib"
 
 - reg:

Documentation/devicetree/bindings/input/rotary-encoder.txt

@@ -12,7 +12,7 @@ Optional properties:
 - rotary-encoder,relative-axis: register a relative axis rather than an
   absolute one. Relative axis will only generate +1/-1 events on the input
   device, hence no steps need to be passed.
-- rotary-encoder,rollover: Automatic rollove when the rotary value becomes
+- rotary-encoder,rollover: Automatic rollover when the rotary value becomes
   greater than the specified steps or smaller than 0. For absolute axis only.
 - rotary-encoder,steps-per-period: Number of steps (stable states) per period.
   The values have the following meaning:

Documentation/devicetree/bindings/input/touchscreen/ad7879.txt

@@ -35,6 +35,7 @@ Optional properties:
 - adi,conversion-interval:	: 0    : convert one time only
 				  1-255: 515us + val * 35us (up to 9.440ms)
 				  This property has to be a '/bits/ 8' value
+- gpio-controller		: Switch AUX/VBAT/GPIO pin to GPIO mode
 
 Example:
 
@@ -51,3 +52,21 @@ Example:
 		adi,averaging = /bits/ 8 <1>;
 		adi,conversion-interval = /bits/ 8 <255>;
 	};
+
+	ad7879@1 {
+		compatible = "adi,ad7879";
+		spi-max-frequency = <5000000>;
+		reg = <1>;
+		spi-cpol;
+		spi-cpha;
+		gpio-controller;
+		interrupt-parent = <&gpio1>;
+		interrupts = <13 IRQ_TYPE_EDGE_FALLING>;
+		touchscreen-max-pressure = <4096>;
+		adi,resistance-plate-x = <120>;
+		adi,first-conversion-delay = /bits/ 8 <3>;
+		adi,acquisition-time = /bits/ 8 <1>;
+		adi,median-filter-size = /bits/ 8 <2>;
+		adi,averaging = /bits/ 8 <1>;
+		adi,conversion-interval = /bits/ 8 <255>;
+	};

Documentation/devicetree/bindings/input/touchscreen/ar1021.txt

+* Microchip AR1020 and AR1021 touchscreen interface (I2C)
+
+Required properties:
+- compatible		: "microchip,ar1021-i2c"
+- reg			: I2C slave address
+- interrupt-parent	: the phandle for the interrupt controller
+- interrupts		: touch controller interrupt
+
+Example:
+
+	touchscreen@4d {
+		compatible = "microchip,ar1021-i2c";
+		reg = <0x4d>;
+		interrupt-parent = <&gpio3>;
+		interrupts = <11 IRQ_TYPE_LEVEL_HIGH>;
+	};

Documentation/devicetree/bindings/input/touchscreen/max11801-ts.txt

+* MAXI MAX11801 Resistive touch screen controller with i2c interface
+
+Required properties:
+- compatible: must be "maxim,max11801"
+- reg: i2c slave address
+- interrupt-parent: the phandle for the interrupt controller
+- interrupts: touch controller interrupt
+
+Example:
+
+&i2c1 {
+	max11801: touchscreen@48 {
+		compatible = "maxim,max11801";
+		reg = <0x48>;
+		interrupt-parent = <&gpio3>;
+		interrupts = <31 IRQ_TYPE_EDGE_FALLING>;
+	};
+};

Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt

 * GSL 1680 touchscreen controller
 
 Required properties:
-- compatible		  : "silead,gsl1680"
+- compatible		  : Must be one of the following, depending on the model:
+			    "silead,gsl1680"
+			    "silead,gsl1688"
+			    "silead,gsl3670"
+			    "silead,gsl3675"
+			    "silead,gsl3692"
 - reg			  : I2C slave address of the chip (0x40)
 - interrupt-parent	  : a phandle pointing to the interrupt controller
 			    serving the interrupt for this chip

Documentation/input/cd32.txt

-I have written a small patch that let's me use my Amiga CD32
-joypad connected to the parallel port. Thought I'd share it with you so
-you can add it to the list of supported joysticks (hopefully someone will
-find it useful).
-
-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 (Fire3)  |   14 (AUTOFD)
-6 (Fire1)  |   17 (SELIN)
-7 (+5V)    |    1 (STROBE)
-8 (Gnd)    |   18 (Gnd)
-9 (Fire2)  |    7 (D5)
-

Documentation/input/conf.py

+# -*- coding: utf-8; mode: python -*-
+
+project = "The Linux input driver subsystem"
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', 'linux-input.tex', project,
+     'The kernel development community', 'manual'),
+]

Documentation/input/alps.txt → Documentation/input/devices/alps.rst

+----------------------
 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.
+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
@@ -78,7 +79,7 @@ of the EC response.
 Packet Format
 -------------
 
-In the following tables, the following notation is used.
+In the following tables, the following notation is used::
 
  CAPITALS = stick, miniscules = touchpad
 
@@ -88,6 +89,8 @@ 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
@@ -99,7 +102,9 @@ 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
@@ -111,6 +116,8 @@ ALPS Absolute Mode - Protocol Version 1
 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
@@ -127,6 +134,8 @@ 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
@@ -149,7 +158,7 @@ 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.
+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
@@ -165,7 +174,7 @@ 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).
+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
@@ -178,7 +187,7 @@ 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.
+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
@@ -190,7 +199,7 @@ The final v3 packet type is the trackstick packet.
 ALPS Absolute Mode - Protocol Version 4
 ---------------------------------------
 
-Protocol version 4 has an 8-byte packet format.
+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
@@ -203,7 +212,7 @@ Protocol version 4 has an 8-byte packet format.
 
 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:
+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
@@ -238,7 +247,7 @@ 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:
+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
@@ -247,7 +256,7 @@ For single-touch, the 6-byte packet format is:
  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:
+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
@@ -259,7 +268,7 @@ For mt, the format is:
 ALPS Absolute Mode - Protocol Version 6
 ---------------------------------------
 
-For trackstick packet, the format is:
+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
@@ -268,7 +277,7 @@ For trackstick packet, the format is:
  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:
+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
@@ -282,7 +291,7 @@ For touchpad packet, the format is:
 ALPS Absolute Mode - Protocol Version 7
 ---------------------------------------
 
-For trackstick packet, the format is:
+For trackstick packet, the format is::
 
  byte 0:    0    1    0    0    1    0    0    0
  byte 1:    1    1    *    *    1    M    R    L
@@ -291,7 +300,7 @@ For trackstick packet, the format is:
  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:
+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
@@ -328,7 +337,7 @@ 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):
+Touchpad packet (APD = 0x2)::
 
            b7   b6   b5   b4   b3   b2   b1   b0
  byte 0:  SWM  SWR  SWL    1    1    0    0   X7
@@ -340,7 +349,7 @@ Touchpad packet (APD = 0x2):
 
 SWM, SWR, SWL: Middle, Right, and Left button states
 
-Touchpad 1 Finger packet (APD = 0x0):
+Touchpad 1 Finger packet (APD = 0x0)::
 
            b7   b6   b5   b4   b3   b2   b1   b0
  byte 0:  SWM  SWR  SWL    1    1   X2   X1   X0
@@ -353,7 +362,7 @@ Touchpad 1 Finger packet (APD = 0x0):
 TAPF: ???
 LFB:  ???
 
-Touchpad 2 Finger packet (APD = 0x1):
+Touchpad 2 Finger packet (APD = 0x1)::
 
            b7   b6   b5   b4   b3   b2   b1   b0
  byte 0:  SWM  SWR  SWL    1    1  AX6  AX5  AX4
@@ -365,7 +374,7 @@ Touchpad 2 Finger packet (APD = 0x1):
 
 CONT: A 3-or-4 Finger packet is to follow
 
-Touchpad 3-or-4 Finger packet (APD = 0x3):
+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

Documentation/input/amijoy.txt → Documentation/input/devices/amijoy.rst

+~~~~~~~~~~~~~~~~~~~~~~~~~
+Amiga joystick extensions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
 Amiga 4-joystick parport extension
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Parallel port pins:
 
- (2) - Up1	 (6) - Up2
- (3) - Down1	 (7) - Down2
- (4) - Left1	 (8) - Left2
- (5) - Right1	 (9) - Right2
-(13) - Fire1	(11) - Fire2
-(18) - Gnd1	(18) - Gnd2
+
+=====  ======== ====   ==========
+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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-(1) - Up
-(2) - Down
-(3) - Left
-(4) - Right
-(5) - n/c
-(6) - Fire button
-(7) - +5V (50mA)
-(8) - Gnd
-(9) - Thumb button
+
+=== ============
+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
 ~~~~~~~~~~~~~~~~~~
-(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
+
+=== ============
+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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-(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
+
+=== ==============
+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
 ~~~~~~~~~~~~~~~~~~~~~
-(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
+
+=== =============
+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
@@ -71,12 +105,17 @@ JOY1DAT      00C   R   Denise Joystick-mouse 1 data (right vert,horiz)
         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)
 
+        - 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
@@ -86,14 +125,21 @@ JOY1DAT   Y7  Y6  Y5  Y4  Y3  Y2  Y1  Y0     X7  X6  X5  X4  X3  X2  X1  X0
 
          +-------------------+-----------------------------------------+
          | 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)     |
          +--------+----------+-----------------------------------------+
 
@@ -104,46 +150,65 @@ JOY1DAT   Y7  Y6  Y5  Y4  Y3  Y2  Y1  Y0     X7  X6  X5  X4  X3  X2  X1  X0
 
          +------------+------+---------------------------------+
          | 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    |
          +-------+------+-----+-----+-------+
 
@@ -155,30 +220,44 @@ POT1DAT  h  014   R   Paula  Pot counter data right pair (vert,horiz)
 
 -------------------------------------------------------------------------------
 
+====== === ==== ==== ====== ================================================
 NAME   rev ADDR type chip   Description
-POTGO      034   W   Paula  Pot port (4 bit) bi-direction and data, and pot counter start.
+====== === ==== ==== ====== ================================================
+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) |
          +-------+----------+---------------------------------------------+
-
--------------------------------------------------------------------------------

Documentation/input/appletouch.txt → Documentation/input/devices/appletouch.rst

+.. include:: <isonum.txt>
+
+----------------------------------
 Apple Touchpad Driver (appletouch)
 ----------------------------------
-	Copyright (C) 2005 Stelian Pop <stelian@popies.net>
+
+: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[1], but it has
-been improved in some areas:
+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.
@@ -16,8 +21,8 @@ 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:
-------
+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
@@ -27,9 +32,9 @@ 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 [2]), 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.
+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"
@@ -60,8 +65,8 @@ example). For additional configuration, see the synaptics driver documentation.
 	...
 	EndSection
 
-Fuzz problems:
---------------
+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
@@ -73,13 +78,17 @@ 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):
+full tracing (each sample is being traced)::
+
 	modprobe appletouch debug=1
-		or
+
+or::
+
 	echo "1" > /sys/module/appletouch/parameters/debug
 
-Links:
-------
 
-[1]: http://johannes.sipsolutions.net/PowerBook/touchpad/
-[2]: http://web.archive.org/web/*/http://web.telia.com/~u89404340/touchpad/index.html
+.. Links:
+
+.. [#f1] http://johannes.sipsolutions.net/PowerBook/touchpad/
+
+.. [#f2] `<http://web.archive.org/web/*/http://web.telia.com/~u89404340/touchpad/index.html>`_

Documentation/input/atarikbd.txt → Documentation/input/devices/atarikbd.rst

+====================================
 Intelligent Keyboard (ikbd) Protocol
+====================================
 
 
-1. Introduction
+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
@@ -18,7 +21,8 @@ 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.
 
-3. Keyboard
+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
@@ -28,6 +32,10 @@ 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
@@ -36,11 +44,13 @@ The special codes 0xF6 through 0xFF are reserved for use as follows:
     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.
 
-4. Mouse
+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
@@ -53,7 +63,8 @@ key equivalents.
 The mouse buttons can be treated as part of the mouse or as additional
 keyboard keys.
 
-4.1 Relative Position Reporting
+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
@@ -67,7 +78,8 @@ 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):
+(regardless of keyboard mode)::
+
     %111110xy           ; mouse position record flag
                         ; where y is the right button state
                         ; and x is the left button state
@@ -81,13 +93,15 @@ If the accumulated motion before the report packet is generated exceeds the
 Note that the sign of the delta y reported is a function of the Y origin
 selected.
 
-4.2 Absolute Position reporting
+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.
 
-4.3 Mouse Cursor Key Mode
+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
@@ -99,32 +113,38 @@ 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).
 
-5. Joystick
+Joystick
+========
 
-5.1 Joystick Event Reporting
+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:
+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
 
-5.2 Joystick Interrogation
+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
+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
 
-5.3 Joystick Monitoring
+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.
@@ -132,7 +152,8 @@ 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).
 
-5.4 Fire Button Monitoring
+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
@@ -142,7 +163,8 @@ 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).
 
-5.5 Joystick Key Code Mode
+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
@@ -152,18 +174,21 @@ 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).
 
-6. Time-of-Day Clock
+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.
 
-7. Status Inquiries
+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.
 
-8. Power-Up Mode
+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
@@ -183,13 +208,17 @@ 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).
 
-9. ikbd Command Set
+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).
 
-9.1 RESET
+RESET
+-----
+
+::
 
     0x80
     0x01
@@ -208,7 +237,10 @@ 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).
 
-9.2. SET MOUSE BUTTON ACTION
+SET MOUSE BUTTON ACTION
+-----------------------
+
+::
 
     0x07
     %00000mss           ; mouse button action
@@ -224,7 +256,10 @@ 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.
 
-9.3 SET RELATIVE MOUSE POSITION REPORTING
+SET RELATIVE MOUSE POSITION REPORTING
+-------------------------------------
+
+::
 
     0x08
 
@@ -235,7 +270,10 @@ 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.
 
-9.4 SET ABSOLUTE MOUSE POSITIONING
+SET ABSOLUTE MOUSE POSITIONING
+------------------------------
+
+::
 
     0x09
     XMSB                ; X maximum (in scaled mouse clicks)
@@ -250,7 +288,10 @@ 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.
 
-9.5 SET MOUSE KEYCODE MOSE
+SET MOUSE KEYCODE MOSE
+----------------------
+
+::
 
     0x0A
     deltax              ; distance in X clicks to return (LEFT) or (RIGHT)
@@ -263,7 +304,10 @@ 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.
 
-9..6 SET MOUSE THRESHOLD
+SET MOUSE THRESHOLD
+-------------------
+
+::
 
     0x0B
     X                   ; x threshold in mouse ticks (positive integers)
@@ -274,7 +318,10 @@ 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).
 
-9.7 SET MOUSE SCALE
+SET MOUSE SCALE
+---------------
+
+::
 
     0x0C
     X                   ; horizontal mouse ticks per internal X
@@ -288,7 +335,10 @@ 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).
 
-9.8 INTERROGATE MOUSE POSITION
+INTERROGATE MOUSE POSITION
+--------------------------
+
+::
 
     0x0D
     Returns:
@@ -306,7 +356,10 @@ or release (see SET MOSE BUTTON ACTION).
 The INTERROGATE MOUSE POSITION command is valid when in the ABSOLUTE MOUSE
 POSITIONING mode, regardless of the setting of the MOUSE BUTTON ACTION.
 
-9.9 LOAD MOUSE POSITION
+LOAD MOUSE POSITION
+-------------------
+
+::
 
     0x0E
     0x00                ; filler
@@ -318,7 +371,10 @@ POSITIONING mode, regardless of the setting of the MOUSE BUTTON ACTION.
 This command allows the user to preset the internally maintained absolute
 mouse position.
 
-9.10 SET Y=0 AT BOTTOM
+SET Y=0 AT BOTTOM
+-----------------
+
+::
 
     0x0F
 
@@ -327,7 +383,10 @@ 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.
 
-9.11 SET Y=0 AT TOP
+SET Y=0 AT TOP
+--------------
+
+::
 
     0x10
 
@@ -336,7 +395,10 @@ 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.
 
-9.12 RESUME
+RESUME
+------
+
+::
 
     0x11
 
@@ -345,7 +407,10 @@ 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.
 
-9.13 DISABLE MOUSE
+DISABLE MOUSE
+-------------
+
+::
 
     0x12
 
@@ -356,7 +421,10 @@ 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.
 
-9.14 PAUSE OUTPUT
+PAUSE OUTPUT
+------------
+
+::
 
     0x13
 
@@ -381,21 +449,30 @@ 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).
 
-0.15 SET JOYSTICK EVENT REPORTING
+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.
 
-9.16 SET JOYSTICK INTERROGATION MODE
+SET JOYSTICK INTERROGATION MODE
+-------------------------------
+
+::
 
     0x15
 
 Disables JOYSTICK EVENT REPORTING. Host must send individual JOYSTICK
 INTERROGATE commands to sense joystick state.
 
-9.17 JOYSTICK INTERROGATE
+JOYSTICK INTERROGATE
+--------------------
+
+::
 
     0x16
 
@@ -403,7 +480,10 @@ 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.
 
-9.18 SET JOYSTICK MONITORING
+SET JOYSTICK MONITORING
+-----------------------
+
+::
 
     0x17
     rate                ; time between samples in hundredths of a second
@@ -419,7 +499,10 @@ 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.
 
-9.19 SET FIRE BUTTON MONITORING
+SET FIRE BUTTON MONITORING
+--------------------------
+
+::
 
     0x18
     Returns: (as long as in mode)
@@ -432,7 +515,10 @@ 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.
 
-9.20 SET JOYSTICK KEYCODE MODE
+SET JOYSTICK KEYCODE MODE
+-------------------------
+
+::
 
     0x19
     RX                  ; length of time (in tenths of seconds) until
@@ -462,7 +548,10 @@ 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.
 
-9.21 DISABLE JOYSTICKS
+DISABLE JOYSTICKS
+-----------------
+
+::
 
     0x1A
 
@@ -472,7 +561,10 @@ joystick mode commands are SET JOYSTICK EVENT REPORTING, SET JOYSTICK
 INTERROGATION MODE, SET JOYSTICK MONITORING, SET FIRE BUTTON MONITORING, and
 SET JOYSTICK KEYCODE MODE.)
 
-9.22 TIME-OF-DAY CLOCK SET
+TIME-OF-DAY CLOCK SET
+---------------------
+
+::
 
     0x1B
     YY                  ; year (2 least significant digits)
@@ -487,7 +579,10 @@ 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.
 
-9.23 INTERROGATE TIME-OF-DAT CLOCK
+INTERROGATE TIME-OF-DAT CLOCK
+-----------------------------
+
+::
 
     0x1C
     Returns:
@@ -501,7 +596,10 @@ only some subfields of the time-of-day clock.
 
     All time-of-day is sent in packed BCD format.
 
-9.24 MEMORY LOAD
+MEMORY LOAD
+-----------
+
+::
 
     0x20
     ADRMSB              ; address in controller
@@ -512,7 +610,10 @@ only some subfields of the time-of-day clock.
 This command permits the host to load arbitrary values into the ikbd
 controller memory. The time between data bytes must be less than 20ms.
 
-9.25 MEMORY READ
+MEMORY READ
+-----------
+
+::
 
     0x21
     ADRMSB              ; address in controller
@@ -524,7 +625,10 @@ controller memory. The time between data bytes must be less than 20ms.
 
 This command permits the host to read from the ikbd controller memory.
 
-9.26 CONTROLLER EXECUTE
+CONTROLLER EXECUTE
+------------------
+
+::
 
     0x22
     ADRMSB              ; address of subroutine in
@@ -533,7 +637,10 @@ This command permits the host to read from the ikbd controller memory.
 This command allows the host to command the execution of a subroutine in the
 ikbd controller memory.
 
-9.27 STATUS INQUIRIES
+STATUS INQUIRIES
+----------------
+
+::
 
     Status commands are formed by inclusively ORing 0x80 with the
     relevant SET command.
@@ -568,7 +675,7 @@ 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:
+    Valid STATUS INQUIRY commands are::
 
             0x87    mouse button action
             0x88    mouse mode
@@ -595,14 +702,17 @@ STATUS INQUIRY commands are not valid if the ikbd is in JOYSTICK MONITORING
 mode or FIRE BUTTON MONITORING mode.
 
 
-10. SCAN CODES
+SCAN CODES
+==========
 
 The key scan codes returned by the ikbd are chosen to simplify the
 implementation of GSX.
 
-GSX Standard Keyboard Mapping.
+GSX Standard Keyboard Mapping
 
+======= ============
 Hex	Keytop
+======= ============
 01	Esc
 02	1
 03	2
@@ -614,8 +724,8 @@ Hex	Keytop
 09	8
 0A	9
 0B	0
-0C	-
-0D	==
+0C	\-
+0D	\=
 0E	BS
 0F	TAB
 10	Q
@@ -643,9 +753,9 @@ Hex	Keytop
 26	L
 27	;
 28	'
-29	`
+29	\`
 2A	(LEFT) SHIFT
-2B	\
+2B	\\
 2C	Z
 2D	X
 2E	C
@@ -707,3 +817,4 @@ Hex	Keytop
 70	KEYPAD 0
 71	KEYPAD .
 72	KEYPAD ENTER
+======= ============

Documentation/input/bcm5974.txt → Documentation/input/devices/bcm5974.rst

+.. include:: <isonum.txt>
+
+------------------------
 BCM5974 Driver (bcm5974)
 ------------------------
-	Copyright (C) 2008-2009	Henrik Rydberg <rydberg@euromail.se>
+
+: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 (C) 2008	Scott Shawcroft (scott.shawcroft@gmail.com)
+
+:Copyright: |copy| 2008	Scott Shawcroft (scott.shawcroft@gmail.com)
 
 The BCM5974 driver is based on the appletouch driver:
-	Copyright (C) 2001-2004	Greg Kroah-Hartman (greg@kroah.com)
-	Copyright (C) 2005	Johannes Berg (johannes@sipsolutions.net)
-	Copyright (C) 2005	Stelian Pop (stelian@popies.net)
-	Copyright (C) 2005	Frank Arnold (frank@scirocco-5v-turbo.de)
-	Copyright (C) 2005	Peter Osterlund (petero2@telia.com)
-	Copyright (C) 2005	Michael Hanselmann (linux-kernel@hansmi.ch)
-	Copyright (C) 2006	Nicolas Boichat (nicolas@boichat.ch)
+
+: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
@@ -44,22 +50,21 @@ 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):
+yields different levels of verbosity. Example (as root)::
 
-echo -n 9 > /sys/module/bcm5974/parameters/debug
+    echo -n 9 > /sys/module/bcm5974/parameters/debug
 
-tail -f /var/log/debug
+    tail -f /var/log/debug
 
-echo -n 0 > /sys/module/bcm5974/parameters/debug
+    echo -n 0 > /sys/module/bcm5974/parameters/debug
 
 Trivia
 ------
 
-The driver was developed at the ubuntu forums in June 2008 [1], and now has
-a more permanent home at bitmath.org [2].
+The driver was developed at the ubuntu forums in June 2008 [#f1]_, and now has
+a more permanent home at bitmath.org [#f2]_.
 
-Links
------
+.. Links
 
-[1] http://ubuntuforums.org/showthread.php?t=840040
-[2] http://bitmath.org/code/
+.. [#f1] http://ubuntuforums.org/showthread.php?t=840040
+.. [#f2] http://bitmath.org/code/

Documentation/input/cma3000_d0x.txt → Documentation/input/devices/cma3000_d0x.rst

-Kernel driver for CMA3000-D0x
-============================
+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>
+: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.
+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.
+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.
+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.
+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.
@@ -38,28 +45,40 @@ 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_x:
+    Noise on X Axis
 
-fuzz_z: Noise on Z Axis
+fuzz_y:
+    Noise on Y Axis
 
-g_range: G range in milli g i.e 2000 or 8000
+fuzz_z:
+    Noise on Z Axis
 
-mode: Default Operating mode
+g_range:
+    G range in milli g i.e 2000 or 8000
 
-mdthr: Motion detect g range threshold value
+mode:
+    Default Operating mode
+
+mdthr:
+    Motion detect g range threshold value
 
-mdfftmr: Motion detect and free fall time threshold value
+mdfftmr:
+    Motion detect and free fall time threshold value
 
-ffthr: Free fall g range 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:
+
+Supported events::
+
   Event type 0 (Sync)
   Event type 3 (Absolute)
     Event code 0 (X)
@@ -87,7 +106,8 @@ Supported events:
 Register/Platform parameters Description
 ----------------------------------------
 
-mode:
+mode::
+
 	0: power down mode
 	1: 100 Hz Measurement mode
 	2: 400 Hz Measurement mode
@@ -97,19 +117,23 @@ mode:
 	6: 40 Hz Free fall mode
 	7: Power off mode
 
-grange:
+grange::
+
 	2000: 2000 mg or 2G Range
 	8000: 8000 mg or 8G Range
 
-mdthr:
+mdthr::
+
 	X: X * 71mg (8G Range)
 	X: X * 18mg (2G Range)
 
-mdfftmr:
+mdfftmr::
+
 	X: (X & 0x70) * 100 ms (MDTMR)
 	   (X & 0x0F) * 2.5 ms (FFTMR 400 Hz)
 	   (X & 0x0F) * 10 ms  (FFTMR 100 Hz)
 
-ffthr:
+ffthr::
+
        X: (X >> 2) * 18mg (2G Range)
        X: (X & 0x0F) * 71 mg (8G Range)

Documentation/input/cs461x.txt → Documentation/input/devices/cs461x.rst

-Preface.
+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
@@ -21,11 +22,8 @@ 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.
+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.

Documentation/input/elantech.txt → Documentation/input/devices/elantech.rst

@@ -10,9 +10,7 @@ Elantech Touchpad Driver
 	received from Woody at Xandros and forwarded to me
 	by user StewieGriffin at the eeeuser.com forum
 
-
-Contents
-~~~~~~~~
+.. Contents
 
  1. Introduction
  2. Extra knobs
@@ -45,8 +43,8 @@ Contents
 
 
 
-1. Introduction
-   ~~~~~~~~~~~~
+Introduction
+~~~~~~~~~~~~
 
 Currently the Linux Elantech touchpad driver is aware of four different
 hardware versions unimaginatively called version 1,version 2, version 3
@@ -88,11 +86,8 @@ available Elantech documentation the information is provided here anyway for
 completeness sake.
 
 
-/////////////////////////////////////////////////////////////////////////////
-
-
-2. Extra knobs
-   ~~~~~~~~~~~
+Extra knobs
+~~~~~~~~~~~
 
 Currently the Linux Elantech touchpad driver provides three extra knobs under
 /sys/bus/serio/drivers/psmouse/serio? for the user.
@@ -142,18 +137,17 @@ Currently the Linux Elantech touchpad driver provides three extra knobs under
    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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-3. Differentiating hardware versions
-   =================================
-
-To detect the hardware version, read the version number as param[0].param[1].param[2]
+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.
+02.00.00, 02.00.04, 02.00.06::
 
  6 bytes:
  02.00.30 => EF113
@@ -162,6 +156,7 @@ In the wild, there appear to be more versions, such as 00.01.64, 01.00.21,
  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.
@@ -170,21 +165,20 @@ 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.
 
-/////////////////////////////////////////////////////////////////////////////
 
-4. Hardware version 1
-   ==================
+Hardware version 1
+~~~~~~~~~~~~~~~~~~
 
-4.1 Registers
-    ~~~~~~~~~
+Registers
+---------
 
 By echoing a hexadecimal value to a register it contents can be altered.
 
-For example:
+For example::
 
    echo -n 0x16 > reg_10
 
-* reg_10
+* reg_10::
 
    bit   7   6   5   4   3   2   1   0
          B   C   T   D   L   A   S   E
@@ -198,7 +192,7 @@ For example:
          C: 1 = enable corner tap
          B: 1 = swap left and right button
 
-* reg_11
+* reg_11::
 
    bit   7   6   5   4   3   2   1   0
          1   0   0   H   V   1   F   P
@@ -208,40 +202,41 @@ For example:
          V: 1 = enable vertical scroll area
          H: 1 = enable horizontal scroll area
 
-* reg_20
+* reg_20::
 
          single finger width?
 
-* reg_21
+* reg_21::
 
          scroll area width (small: 0x40 ... wide: 0xff)
 
-* reg_22
+* reg_22::
 
          drag lock time out (short: 0x14 ... long: 0xfe;
                              0xff = tap again to release)
 
-* reg_23
+* reg_23::
 
          tap make timeout?
 
-* reg_24
+* reg_24::
 
          tap release timeout?
 
-* reg_25
+* reg_25::
 
          smart edge cursor speed (0x02 = slow, 0x03 = medium, 0x04 = fast)
 
-* reg_26
+* reg_26::
 
          smart edge activation area width?
 
 
-4.2 Native relative mode 4 byte packet format
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Native relative mode 4 byte packet format
+-----------------------------------------
+
+byte 0::
 
-byte 0:
    bit   7   6   5   4   3   2   1   0
          c   c  p2  p1   1   M   R   L
 
@@ -251,20 +246,23 @@ byte 0:
             p1..p2 = byte 1 and 2 odd parity bit
          c = 1 when corner tap detected
 
-byte 1:
+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:
+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:
+byte 3::
+
    parity checking enabled (reg_11, P = 1):
 
       bit   7   6   5   4   3   2   1   0
@@ -296,14 +294,15 @@ byte 3:
                        positive = down
 
 
-4.3 Native absolute mode 4 byte packet format
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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:
+byte 0::
+
    firmware version 1.x:
 
       bit   7   6   5   4   3   2   1   0
@@ -322,7 +321,8 @@ byte 0:
             p1..p3 = byte 1..3 odd parity bit
             n1..n0 = number of fingers on touchpad
 
-byte 1:
+byte 1::
+
    firmware version 1.x:
 
       bit   7   6   5   4   3   2   1   0
@@ -337,65 +337,68 @@ byte 1:
       bit   7   6   5   4   3   2   1   0
             .   .   .   .  x9  x8  y9  y8
 
-byte 2:
+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:
+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
+~~~~~~~~~~~~~~~~~~
 
-5. Hardware version 2
-   ==================
 
-
-5.1 Registers
-    ~~~~~~~~~
+Registers
+---------
 
 By echoing a hexadecimal value to a register it contents can be altered.
 
-For example:
+For example::
 
    echo -n 0x56 > reg_10
 
-* 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
+* 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
+* reg_21::
 
          unknown (0x00)
 
-* reg_22
+* reg_22::
 
          drag and drop release time out (short: 0x70 ... long 0x7e;
                                    0x7f = never i.e. tap again to release)
 
 
-5.2 Native absolute mode 6 byte packet format
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-5.2.1 Parity checking and packet re-synchronization
+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:
+For instance for EF113::
+
         SA1= packet[0];
         A1 = packet[1];
         B1 = packet[2];
@@ -410,7 +413,8 @@ For instance for EF113:
             (((SA1 & 0xC0) != 0x80) && (( C1 & 0xF0) != 0x00))  ) // check Byte 5
 		// error detected
 
-For all the other ones, there are just a few constant bits:
+For all the other ones, there are just a few constant bits::
+
         if( ((packet[0] & 0x0C) != 0x04) ||
             ((packet[3] & 0x0f) != 0x02) )
 		// error detected
@@ -418,10 +422,10 @@ For all the other ones, there are just a few constant bits:
 
 In case an error is detected, all the packets are shifted by one (and packet[0] is discarded).
 
-5.2.2 One/Three finger touch
-      ~~~~~~~~~~~~~~~~
+One/Three finger touch
+^^^^^^^^^^^^^^^^^^^^^^
 
-byte 0:
+byte 0::
 
    bit   7   6   5   4   3   2   1   0
 	 n1  n0  w3  w2   .   .   R   L
@@ -429,19 +433,19 @@ byte 0:
          L, R = 1 when Left, Right mouse button pressed
          n1..n0 = number of fingers on touchpad
 
-byte 1:
+byte 1::
 
    bit   7   6   5   4   3   2   1   0
 	 p7  p6  p5  p4 x11 x10 x9  x8
 
-byte 2:
+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:
+byte 3::
 
    bit   7   6   5   4   3   2   1   0
 	 n4  vf  w1  w0   .   .   .  b2
@@ -460,14 +464,14 @@ byte 3:
 		6 = Another one
 		7 = Another one
 
-byte 4:
+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:
+byte 5::
 
    bit   7   6   5   4   3   2   1   0
         y7  y6  y5  y4  y3  y2  y1  y0
@@ -475,15 +479,15 @@ byte 5:
          y11..y0 = absolute y value (vertical)
 
 
-5.2.3 Two finger touch
-      ~~~~~~~~~~~~~~~~
+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:
+byte 0::
 
    bit   7   6   5   4   3   2   1   0
         n1  n0  ay8 ax8  .   .   R   L
@@ -491,47 +495,46 @@ byte 0:
          L, R = 1 when Left, Right mouse button pressed
          n1..n0 = number of fingers on touchpad
 
-byte 1:
+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:
+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:
+byte 3::
 
    bit   7   6   5   4   3   2   1   0
          .   .  by8 bx8  .   .   .   .
 
-byte 4:
+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:
+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
+~~~~~~~~~~~~~~~~~~
 
-6. Hardware version 3
-   ==================
+Registers
+---------
 
-6.1 Registers
-    ~~~~~~~~~
-* reg_10
+* reg_10::
 
    bit   7   6   5   4   3   2   1   0
          0   0   0   0   R   F   T   A
@@ -541,8 +544,9 @@ byte 5:
          F: 1 = disable ABS Position Filter
          R: 1 = enable real hardware resolution
 
-6.2 Native absolute mode 6 byte packet format
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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.
 
@@ -552,19 +556,21 @@ 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:
+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.
 
-6.2.1 One/Three finger touch
-      ~~~~~~~~~~~~~~~~~~~~~~
+One/Three finger touch
+^^^^^^^^^^^^^^^^^^^^^^
 
-byte 0:
+byte 0::
 
    bit   7   6   5   4   3   2   1   0
         n1  n0  w3  w2   0   1   R   L
@@ -572,63 +578,63 @@ byte 0:
         L, R = 1 when Left, Right mouse button pressed
         n1..n0 = number of fingers on touchpad
 
-byte 1:
+byte 1::
 
    bit   7   6   5   4   3   2   1   0
         p7  p6  p5  p4 x11 x10  x9  x8
 
-byte 2:
+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:
+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:
+byte 4::
 
    bit   7   6   5   4   3   2   1   0
         p3  p1  p2  p0  y11 y10 y9  y8
 
         p7..p0 = pressure
 
-byte 5:
+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)
 
-6.2.2 Two finger touch
-      ~~~~~~~~~~~~~~~~
+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
+~~~~~~~~~~~~~~~~~~
 
-7. Hardware version 4
-   ==================
+Registers
+---------
 
-7.1 Registers
-    ~~~~~~~~~
-* reg_07
+* reg_07::
 
    bit   7   6   5   4   3   2   1   0
          0   0   0   0   0   0   0   A
 
          A: 1 = enable absolute tracking
 
-7.2 Native absolute mode 6 byte packet format
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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.
@@ -647,45 +653,49 @@ 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.
 
-7.2.1 Status packet
-      ~~~~~~~~~~~~~
+Status packet
+^^^^^^^^^^^^^
 
-byte 0:
+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:
+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 2::
+
+   not used
 
-byte 3:
+byte 3::
 
    bit   7   6   5   4   3   2   1   0
          .   .   .   1   0   0   0   0
 
          constant bits
 
-byte 4:
+byte 4::
 
    bit   7   6   5   4   3   2   1   0
          p   .   .   .   .   .   .   .
 
          p = 1 for palm
 
-byte 5: not used
+byte 5::
 
-7.2.2 Head packet
-      ~~~~~~~~~~~
+   not used
 
-byte 0:
+Head packet
+^^^^^^^^^^^
+
+byte 0::
 
    bit   7   6   5   4   3   2   1   0
         w3  w2  w1  w0   0   1   R   L
@@ -693,43 +703,43 @@ byte 0:
         L, R = 1 when Left, Right mouse button pressed
         w3..w0 = finger width (spans how many trace lines)
 
-byte 1:
+byte 1::
 
    bit   7   6   5   4   3   2   1   0
         p7  p6  p5  p4 x11 x10  x9  x8
 
-byte 2:
+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:
+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:
+byte 4::
 
    bit   7   6   5   4   3   2   1   0
         p3  p1  p2  p0  y11 y10 y9  y8
 
         p7..p0 = pressure
 
-byte 5:
+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)
 
-7.2.3 Motion packet
-      ~~~~~~~~~~~~~
+Motion packet
+^^^^^^^^^^^^^
 
-byte 0:
+byte 0::
 
    bit   7   6   5   4   3   2   1   0
        id2 id1 id0   w   0   1   R   L
@@ -739,35 +749,35 @@ byte 0:
        w = 1 when delta overflows (> 127 or < -128), in this case
        firmware sends us (delta x / 5) and (delta y  / 5)
 
-byte 1:
+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:
+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:
+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:
+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:
+byte 5::
 
    bit   7   6   5   4   3   2   1   0
         y7  y6  y5  y4  y3  y2  y1  y0
@@ -778,33 +788,47 @@ byte 5:
         byte 3 ~ 5 for another
 
 
-8. Trackpoint (for Hardware version 3 and 4)
-   =========================================
-8.1 Registers
-    ~~~~~~~~~
+Trackpoint (for Hardware version 3 and 4)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Registers
+---------
+
 No special registers have been identified.
 
-8.2 Native relative mode 6 byte packet format
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-8.2.1 Status Packet
-      ~~~~~~~~~~~~~
+Native relative mode 6 byte packet format
+-----------------------------------------
+
+Status Packet
+^^^^^^^^^^^^^
+
+byte 0::
 
-byte 0:
    bit   7   6   5   4   3   2   1   0
          0   0  sx  sy   0   M   R   L
-byte 1:
+
+byte 1::
+
    bit   7   6   5   4   3   2   1   0
        ~sx   0   0   0   0   0   0   0
-byte 2:
+
+byte 2::
+
    bit   7   6   5   4   3   2   1   0
        ~sy   0   0   0   0   0   0   0
-byte 3:
+
+byte 3::
+
    bit   7   6   5   4   3   2   1   0
          0   0 ~sy ~sx   0   1   1   0
-byte 4:
+
+byte 4::
+
    bit   7   6   5   4   3   2   1   0
         x7  x6  x5  x4  x3  x2  x1  x0
-byte 5:
+
+byte 5::
+
    bit   7   6   5   4   3   2   1   0
         y7  y6  y5  y4  y3  y2  y1  y0
 

Documentation/input/gpio-tilt.txt → Documentation/input/devices/gpio-tilt.rst

@@ -7,8 +7,8 @@ i.e. each tilt switch providing one axis, and the number of axes
 is also not limited.
 
 
-Data structures:
-----------------
+Data structures
+---------------
 
 The array of struct gpio in the gpios field is used to list the gpios
 that represent the current tilt state.
@@ -24,26 +24,26 @@ In the same manner the values stored in the axes array correspond to
 the elements of the gpio_tilt_axis-array.
 
 
-Example:
---------
+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.
+one axis in 4 steps and emits the current tilt via two GPIOs::
 
-static int sg060_tilt_enable(struct device *dev) {
+    static int sg060_tilt_enable(struct device *dev) {
 	    /* code to enable the sensors */
-};
+    };
 
-static void sg060_tilt_disable(struct device *dev) {
+    static void sg060_tilt_disable(struct device *dev) {
 	    /* code to disable the sensors */
-};
+    };
 
-static struct gpio sg060_tilt_gpios[] = {
+    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[] = {
+    static struct gpio_tilt_state sg060_tilt_states[] = {
 	    {
 		    .gpios = (0 << 1) | (0 << 0),
 		    .axes = (int[]) {
@@ -65,9 +65,9 @@ static struct gpio_tilt_state sg060_tilt_states[] = {
 			    3, /* 270 degrees */
 		    },
 	    },
-};
+    };
 
-static struct gpio_tilt_axis sg060_tilt_axes[] = {
+    static struct gpio_tilt_axis sg060_tilt_axes[] = {
 	    {
 		    .axis = ABS_RY,
 		    .min = 0,
@@ -75,9 +75,9 @@ static struct gpio_tilt_axis sg060_tilt_axes[] = {
 		    .fuzz = 0,
 		    .flat = 0,
 	    },
-};
+    };
 
-static struct gpio_tilt_platform_data sg060_tilt_pdata= {
+    static struct gpio_tilt_platform_data sg060_tilt_pdata= {
 	    .gpios = sg060_tilt_gpios,
 	    .nr_gpios = ARRAY_SIZE(sg060_tilt_gpios),
 
@@ -92,12 +92,12 @@ static struct gpio_tilt_platform_data sg060_tilt_pdata= {
 	    .poll_interval = 1000,
 	    .enable = sg060_tilt_enable,
 	    .disable = sg060_tilt_disable,
-};
+    };
 
-static struct platform_device sg060_device_tilt = {
+    static struct platform_device sg060_device_tilt = {
 	    .name = "gpio-tilt-polled",
 	    .id = -1,
 	    .dev = {
 		    .platform_data = &sg060_tilt_pdata,
 	    },
-};
+    };

Documentation/input/iforce-protocol.txt → Documentation/input/devices/iforce-protocol.rst

-** Introduction
+===============
+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
@@ -6,58 +19,83 @@ 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.
+.. 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
+=================
 
-** 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 **
+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.
+== ====
+
+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
+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
+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
+    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
@@ -65,10 +103,11 @@ LEN= 0e
 	    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))
+	    Val 41 Friction (Force = f(velocity)) and Inertia
+	           (Force = f(acceleration))
 
 
-02 Axes affected and trigger
+    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
@@ -77,128 +116,203 @@ LEN= 0e
 		    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
+    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
+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.
+    02 Number of iterations n.
+
+Init
+----
+
 
-** Init **
+Querying features
+^^^^^^^^^^^^^^^^^
+::
 
-*** 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)
+    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)
 
-**** 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)
+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)
+Vendor's id
+~~~~~~~~~~~
+
+::
+
+    QUERY = 4d ('M'anufacturer)
+
 Query the vendors'id (2 bytes)
 
-**** Product id *****
-QUERY = 50 ('P'roduct)
+Product id
+~~~~~~~~~~
+
+::
+
+    QUERY = 50 ('P'roduct)
+
 Query the product id (2 bytes)
 
-**** Open device ****
-QUERY = 4f ('O'pen)
+Open device
+~~~~~~~~~~~
+
+::
+
+    QUERY = 4f ('O'pen)
+
 No data returned.
 
-**** Close device *****
-QUERY = 43 ('C')lose
+Close device
+~~~~~~~~~~~~
+
+::
+
+    QUERY = 43 ('C')lose
+
 No data returned.
 
-**** Query effect ****
-QUERY = 45 ('E')
+Query effect
+~~~~~~~~~~~~
+
+::
+
+    QUERY = 45 ('E')
+
 Send effect type.
 Returns nonzero if supported (2 bytes)
 
-**** Firmware Version ****
-QUERY = 56 ('V'ersion)
+Firmware Version
+~~~~~~~~~~~~~~~~
+
+::
+
+    QUERY = 56 ('V'ersion)
+
 Sends back 3 bytes - major, minor, subminor
 
-*** Initialisation of the device ***
+Initialisation of the device
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set Control
+~~~~~~~~~~~
+
+.. note::
+    Device dependent, can be different on different models!
 
-**** Set Control ****
-!!! Device dependent, can be different on different models !!!
-OP=  40 <idx> <val> [<val>]
-LEN= 2 or 3
-00 Idx
+::
+
+    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)
@@ -206,33 +320,44 @@ LEN= 2 or 3
        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
+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 gain ****
-OP=  43 <val>
-LEN= 1
-00 Gain
+Set overall
+~~~~~~~~~~~
+
+::
+
+    OP=  43 <val>
+    LEN= 1
+    00 Gain
        Val 00 = 0%
        Val 40 = 50%
        Val 80 = 100%
 
-** Parameter memory **
+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 ? **
+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:
@@ -246,13 +371,11 @@ At first glance, this software seems, hum, well... buggy. In fact, data appear w
 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 www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy.
+URLS
+====
 
-** Author of this document **
-Johann Deneux <johann.deneux@gmail.com>
-Home page at http://web.archive.org/web/*/http://www.esil.univ-mrs.fr
+Check http://www.immerse.com for Immersion Studio,
+and http://www.fcoder.com for ComPortSpy.
 
-Additions by Vojtech Pavlik.
 
 I-Force is trademark of Immersion Corp.

Documentation/input/devices/index.rst

+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`

Documentation/input/ntrig.txt → Documentation/input/devices/ntrig.rst

+.. include:: <isonum.txt>
+
+=========================
 N-Trig touchscreen Driver
--------------------------
-	Copyright (c) 2008-2010 Rafi Rubin <rafi@seas.upenn.edu>
-	Copyright (c) 2009-2010 Stephane Chatty
+=========================
+
+: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
@@ -22,16 +26,18 @@ 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
++-----------------------+-----------------------------------------------------+
+|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
@@ -44,15 +50,20 @@ 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
++-----------------------+-----------------------------------------------------+
+|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
+
+* 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

Documentation/input/rotary-encoder.txt → Documentation/input/devices/rotary-encoder.rst

+============================================================
 rotary-encoder - a generic driver for GPIO connected devices
-Daniel Mack <daniel@caiaq.de>, Feb 2009
+============================================================
 
-0. Function
------------
+: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
@@ -13,7 +16,7 @@ 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:
+The phase diagram of these two outputs look like this::
 
                   _____       _____       _____
                  |     |     |     |     |     |
@@ -40,8 +43,8 @@ For more information, please see
 	https://en.wikipedia.org/wiki/Rotary_encoder
 
 
-1. Events / state machine
--------------------------
+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
@@ -65,62 +68,64 @@ d) Falling edge on channel B, channel A in low state
 	should have happened, unless it flipped back on half the way. The
 	'armed' state tells us about that.
 
-2. Platform requirements
-------------------------
+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.
 
 
-3. Board integration
---------------------
+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.
-
-struct rotary_encoder_platform_data is declared in
-include/linux/rotary-encoder.h and needs to be filled with the number of
-steps the encoder has and can carry information about externally inverted
-signals (because of an inverting buffer or other reasons). The encoder
-can be set up to deliver input information as either an absolute or relative
-axes. For relative axes the input event returns +/-1 for each step. For
-absolute axes the position of the encoder can either roll over between zero
-and the number of steps or will clamp at the maximum and zero depending on
-the configuration.
-
-Because GPIO to IRQ mapping is platform specific, this information must
-be given in separately to the driver. See the example below.
-
----------<snip>---------
-
-/* board support file example */
-
-#include <linux/input.h>
-#include <linux/rotary_encoder.h>
-
-#define GPIO_ROTARY_A 1
-#define GPIO_ROTARY_B 2
-
-static struct rotary_encoder_platform_data my_rotary_encoder_info = {
-	.steps		= 24,
-	.axis		= ABS_X,
-	.relative_axis	= false,
-	.rollover	= false,
-	.gpio_a		= GPIO_ROTARY_A,
-	.gpio_b		= GPIO_ROTARY_B,
-	.inverted_a	= 0,
-	.inverted_b	= 0,
-	.half_period	= false,
-	.wakeup_source	= false,
-};
-
-static struct platform_device rotary_encoder_device = {
+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,
-	.dev		= {
-		.platform_data = &my_rotary_encoder_info,
-	}
-};
+	};
+
+	...
+
+	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.

Documentation/input/walkera0701.txt → Documentation/input/devices/walkera0701.rst

+===========================
+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
@@ -10,7 +13,8 @@ or use cogito:
 cg-clone http://zub.fei.tuke.sk/GIT/walkera0701-joystick
 
 
-Connecting to PC:
+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,
@@ -19,7 +23,8 @@ modulation pulses to PC, signal pulses must be amplified.
 
 Cable: (walkera TX to parport)
 
-Walkera WK-0701 TX S-VIDEO connector:
+Walkera WK-0701 TX S-VIDEO connector::
+
  (back side of TX)
      __   __              S-video:                                  canon25
     /  |_|  \             pin 2 (signal)              NPN           parport
@@ -30,10 +35,10 @@ Walkera WK-0701 TX S-VIDEO connector:
      -------        3 __________________________________|________________ 25 GND
                                                           E
 
-
 I use green LED and BC109 NPN transistor.
 
-Software:
+Software
+========
 
 Build kernel with walkera0701 module. Module walkera0701 need exclusive
 access to parport, modules like lp must be unloaded before loading
@@ -44,7 +49,8 @@ be changed by TX "joystick", check output from /proc/interrupts. Value for
 
 
 
-Technical details:
+Technical details
+=================
 
 Driver use interrupt from parport ACK input bit to measure pulse length
 using hrtimers.
@@ -53,17 +59,29 @@ 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:
+Signal pulses
+-------------
+
+::
+
                      (ANALOG)
       SYNC      BIN   OCT
     +---------+      +------+
     |         |      |      |
---+         +------+      +---
+  --+         +------+      +---
+
+Frame
+-----
+
+::
 
-Frame:
  SYNC , BIN1, OCT1, BIN2, OCT2 ... BIN24, OCT24, BIN25, next frame SYNC ..
 
-pulse length:
+pulse length
+------------
+
+::
+
    Binary values:		Analog octal values:
 
    288 uS Binary 0		318 uS       000
@@ -80,7 +98,8 @@ pulse length:
 (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:
+Binary data representations
+---------------------------
 
 One binary and octal value can be grouped to nibble. 24 nibbles + one binary
 values can be sampled between sync pulses.
@@ -100,10 +119,10 @@ 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:
+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.
-

Documentation/input/xpad.txt → Documentation/input/devices/xpad.rst

+=======================================================
 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
@@ -15,9 +17,11 @@ the Xbox One's rumble protocol has not been reverse engineered but in
 the future could be supported.
 
 
-0. Notes
---------
+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
@@ -35,8 +39,9 @@ This is not true. Both dpad_to_buttons and triggers_to_buttons only affect
 unknown controllers.
 
 
-0.1 Normal 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.
@@ -55,8 +60,9 @@ in game functionality were OK. However, I find it rather difficult to
 play first person shooters with a pad. Your mileage may vary.
 
 
-0.2 Xbox Dance Pads
--------------------
+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
@@ -73,24 +79,21 @@ of buttons, see section 0.3 - Unknown Controllers
 I've tested this with Stepmania, and it works quite well.
 
 
-0.3 Unknown Controllers
-----------------------
+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
+============
 
-1. 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'
@@ -101,8 +104,9 @@ All generations of Xbox controllers speak USB over the wire.
 
 
 
-1.1 Original Xbox USB adapters
---------------
+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.
@@ -115,7 +119,7 @@ the controller device) with the only difference in a nonstandard connector
 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]).
+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,
@@ -123,22 +127,46 @@ you can still use the controller with your X-Box, if you have one ;)
 
 
 
-2. Driver Installation
-----------------------
+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].
+/sys/kernel/debug/usb/devices. There should be an entry like those:
+
+.. code-block:: none
+   :caption: 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
 
+.. code-block:: none
+   :caption: 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
+
+
+Supported Controllers
+=====================
 
-3. Supported Controllers
-------------------------
 For a full list of supported controllers and associated vendor and product
-IDs see the xpad_device[] array[6].
+IDs see the xpad_device[] array\ [4]_.
 
 As of the historic version 0.0.6 (2006-10-10) the following devices
-were supported:
+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
@@ -152,14 +180,16 @@ the module option 'dpad_to_buttons'.
 If you have an unrecognized controller please see 0.3 - Unknown Controllers
 
 
-4. Manual Testing
------------------
+Manual Testing
+==============
+
 To test this driver's functionality you may use 'jstest'.
 
-For example:
-> modprobe xpad
-> modprobe joydev
-> jstest /dev/js0
+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
@@ -170,8 +200,8 @@ It works? Voila, you're done ;)
 
 
 
-5. Thanks
----------
+Thanks
+======
 
 I have to thank ITO Takayuki for the detailed info on his site
     http://euc.jp/periphs/xbox-controller.ja.html.
@@ -182,45 +212,22 @@ the basic functionality.
 
 
 
-6. 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
+References
+==========
 
-[6]: http://lxr.free-electrons.com/ident?i=xpad_device
+.. [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] http://lxr.free-electrons.com/ident?i=xpad_device
 
 
+Historic Edits
+==============
 
-7. Historic Edits
------------------
-Marko Friedemann <mfr@bmx-chemnitz.de>
-2002-07-16
+2002-07-16 - Marko Friedemann <mfr@bmx-chemnitz.de>
  - original doc
 
-Dominic Cerquetti <binary1230@yahoo.com>
-2005-03-19
+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'

Documentation/input/index.rst

+=============================
+The Linux Input Documentation
+=============================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   input_uapi
+   input_kapi
+   devices/index
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`