[PATCH 1/8] Input: move documentation for Amiga CD32

[PATCH 1/8] Input: move documentation for Amiga CD32

[Dmitry Torokhov]

Move the documentation for Amiga CD32 together with other parallel port
joysticks.

Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
---
 Documentation/input/cd32.rst             | 24 ---------------------
 Documentation/input/index.rst            |  1 -
 Documentation/input/joystick-parport.rst | 37 ++++++++++++++++++++++++++++++++
 3 files changed, 37 insertions(+), 25 deletions(-)
 delete mode 100644 Documentation/input/cd32.rst

diff --git a/Documentation/input/cd32.rst b/Documentation/input/cd32.rst
deleted file mode 100644
index 935028b957d9..000000000000
--- a/Documentation/input/cd32.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-==========
-Amiga CD32
-==========
-
-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)
-===========    =============
diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst
index 153f0d476c3e..32c0515fd24b 100644
--- a/Documentation/input/index.rst
+++ b/Documentation/input/index.rst
@@ -54,7 +54,6 @@ Input drivers
    appletouch
    atarikbd
    bcm5974
-   cd32
    cma3000_d0x
    cs461x
    edt-ft5x06
diff --git a/Documentation/input/joystick-parport.rst b/Documentation/input/joystick-parport.rst
index 0aa0fb17bf48..fa8cab584793 100644
--- a/Documentation/input/joystick-parport.rst
+++ b/Documentation/input/joystick-parport.rst
@@ -443,6 +443,43 @@ parallel port::
 The other pins (Up, Down, Right, Left, Power, Ground) are the same as for
 Multi joysticks using db9.c
 
+Amiga CD32
+----------
+
+Amiga CD32 joypad uses the following pinout::
+
+        +-----------> Button 3
+        | +---------> Right
+        | | +-------> Left
+        | | | +-----> Down
+        | | | | +---> Up
+        | | | | |
+      _____________
+    5 \ o o o o o / 1
+       \ o o o o /
+      9 `~~~~~~~' 6
+        | | | |
+        | | | +----> Button 1
+        | | +------> Power
+        | +--------> Ground
+        +----------> Button 2
+
+It can be connected to the parallel port and driven by db9.c driver. It needs the following wiring:
+
+	============    =============
+	CD32 pad        Parallel port
+	============    =============
+	1 (Up)           2 (D0)
+	2 (Down)         3 (D1)
+	3 (Left)         4 (D2)
+	4 (Right)        5 (D3)
+	5 (Button 3)    14 (AUTOFD)
+	6 (Button 1)    17 (SELIN)
+	7 (+5V)          1 (STROBE)
+	8 (Gnd)         18 (Gnd)
+	9 (Button 2)     7 (D5)
+	============    =============
+
 The drivers
 ===========
 
-- 
2.12.2.762.g0e3151a226-goog

[PATCH 2/8] Input: rotary-encoder - remove references to platform data from docs

[Dmitry Torokhov]

The driver has been converted to use generic device properties, so
stop referring to platform data.

Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
---
 Documentation/input/rotary-encoder.rst | 85 ++++++++++++++++++----------------
 1 file changed, 44 insertions(+), 41 deletions(-)

diff --git a/Documentation/input/rotary-encoder.rst b/Documentation/input/rotary-encoder.rst
index 4695bea67f9b..b07b20a295ac 100644
--- a/Documentation/input/rotary-encoder.rst
+++ b/Documentation/input/rotary-encoder.rst
@@ -81,48 +81,51 @@ 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.
+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:
 
-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.
+	/* board support file example */
 
-::
+	#include <linux/input.h>
+	#include <linux/gpio/machine.h>
+	#include <linux/property.h>
+
+	#define GPIO_ROTARY_A 1
+	#define GPIO_ROTARY_B 2
+
+	static struct gpiod_lookup_table rotary_encoder_gpios = {
+		.dev_id = "rotary-encoder.0",
+		.table = {
+			GPIO_LOOKUP_IDX("gpio-0",
+					GPIO_ROTARY_A, NULL, 0, GPIO_ACTIVE_LOW),
+			GPIO_LOOKUP_IDX("gpio-0",
+					GPIO_ROTARY_B, NULL, 1, GPIO_ACTIVE_HIGH),
+			{ },
+		},
+	};
+
+	static const struct property_entry rotary_encoder_properties[] __initconst = {
+		PROPERTY_ENTRY_INTEGER("rotary-encoder,steps-per-period", u32, 24),
+		PROPERTY_ENTRY_INTEGER("linux,axis",			  u32, ABS_X),
+		PROPERTY_ENTRY_INTEGER("rotary-encoder,relative_axis",	  u32, 0),
+		{ },
+	};
+
+	static struct platform_device rotary_encoder_device = {
+		.name		= "rotary-encoder",
+		.id		= 0,
+	};
+
+	...
+
+	gpiod_add_lookup_table(&rotary_encoder_gpios);
+	device_add_properties(&rotary_encoder_device, rotary_encoder_properties);
+	platform_device_register(&rotary_encoder_device);
+
+	...
 
-    /* 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 = {
-	    .name		= "rotary-encoder",
-	    .id		= 0,
-	    .dev		= {
-		    .platform_data = &my_rotary_encoder_info,
-	    }
-    };
+Please consult device tree binding documentation to see all properties
+supported by the driver.
-- 
2.12.2.762.g0e3151a226-goog

[PATCH 3/8] Input: fix "Game console" heading level in joystick documentation

[Dmitry Torokhov]

The heading level should be the same as for other devices.

Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
---
 Documentation/input/joystick.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/input/joystick.rst b/Documentation/input/joystick.rst
index 202f5a090675..c9c175ffc2ff 100644
--- a/Documentation/input/joystick.rst
+++ b/Documentation/input/joystick.rst
@@ -465,7 +465,7 @@ No more joystick types are supported now, but that should change in the
 future if I get an Amiga in the reach of my fingers.
 
 Game console and 8-bit pads and joysticks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------
 
 See :ref:`joystick-parport` for more info.
 
-- 
2.12.2.762.g0e3151a226-goog

[PATCH 4/8] Input: docs - remove disclaimer/GPL notice

[Dmitry Torokhov]

This is just a part of kernel documentation, it does not require explicit
license notice.

Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
---
 Documentation/input/index.rst | 21 ---------------------
 1 file changed, 21 deletions(-)

diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst
index 32c0515fd24b..5887c79173b8 100644
--- a/Documentation/input/index.rst
+++ b/Documentation/input/index.rst
@@ -2,27 +2,6 @@
 The Linux Input Documentation
 =============================
 
-Disclaimer
-==========
-
-This program is free software; you can redistribute it and/or modify it
-under the terms of the GNU General Public License as published by the Free
-Software Foundation; either version 2 of the License, or (at your option)
-any later version.
-
-This program is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
-or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
-more details.
-
-You should have received a copy of the GNU General Public License along
-with this program; if not, write to the Free Software Foundation, Inc., 59
-Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
-For your convenience, the GNU General Public License version 2 is included
-in the package: See the file COPYING.
-
-
 Core API
 ========
 
-- 
2.12.2.762.g0e3151a226-goog

[PATCH 5/8] Input: docs - update joystick documentation a bit

[Dmitry Torokhov]

Consolidate use instructions and userspace API notes into the same chapter;
remove completely obsolete references, move into a separate subdirectory.

Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
---
 Documentation/input/index.rst                     |  6 +-
 Documentation/input/joydev/index.rst              | 18 +++++
 Documentation/input/{ => joydev}/joystick-api.rst | 30 ++++++--
 Documentation/input/{ => joydev}/joystick.rst     | 88 ++++++-----------------
 Documentation/input/joystick-parport.rst          | 12 ++--
 5 files changed, 71 insertions(+), 83 deletions(-)
 create mode 100644 Documentation/input/joydev/index.rst
 rename Documentation/input/{ => joydev}/joystick-api.rst (89%)
 rename Documentation/input/{ => joydev}/joystick.rst (86%)

diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst
index 5887c79173b8..b25a67198a65 100644
--- a/Documentation/input/index.rst
+++ b/Documentation/input/index.rst
@@ -2,8 +2,7 @@
 The Linux Input Documentation
 =============================
 
-Core API
-========
+Contents:
 
 .. toctree::
    :maxdepth: 2
@@ -12,8 +11,7 @@ Core API
    input
    input-programming
    event-codes
-   joystick
-   joystick-api
+   joydev/index
    multi-touch-protocol
    gamepad
    gameport-programming
diff --git a/Documentation/input/joydev/index.rst b/Documentation/input/joydev/index.rst
new file mode 100644
index 000000000000..8d9666c7561c
--- /dev/null
+++ b/Documentation/input/joydev/index.rst
@@ -0,0 +1,18 @@
+.. include:: <isonum.txt>
+
+======================
+Linux Joystick support
+======================
+
+:Copyright: |copy| 1996-2000 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE
+
+.. class:: toc-title
+
+	Table of Contents
+
+.. toctree::
+	:maxdepth: 3
+	:numbered:
+
+	joystick
+	joystick-api
diff --git a/Documentation/input/joystick-api.rst b/Documentation/input/joydev/joystick-api.rst
similarity index 89%
rename from Documentation/input/joystick-api.rst
rename to Documentation/input/joydev/joystick-api.rst
index 9b9d26833086..42edcfc6e8af 100644
--- a/Documentation/input/joystick-api.rst
+++ b/Documentation/input/joydev/joystick-api.rst
@@ -1,16 +1,36 @@
-==========================
-Joystick API Documentation
-==========================
+=====================
+Programming Interface
+=====================
 
 :Author: Ragnar Hojland Espinosa <ragnar@macula.net> - 7 Aug 1998
 
+Introduction
+============
+
+.. important::
+   This document describes legacy ``js`` interface. Newer clients are
+   encouraged to switch to the generic event (``evdev``) interface.
+
+The 1.0 driver uses a new, event based approach to the joystick driver.
+Instead of the user program polling for the joystick values, the joystick
+driver now reports only any changes of its state. See joystick-api.txt,
+joystick.h and jstest.c included in the joystick package for more
+information. The joystick device can be used in either blocking or
+nonblocking mode, and supports select() calls.
+
+For backward compatibility the old (v0.x) interface is still included.
+Any call to the joystick driver using the old interface will return values
+that are compatible to the old interface. This interface is still limited
+to 2 axes, and applications using it usually decode only 2 buttons, although
+the driver provides up to 32.
+
 Initialization
 ==============
 
 Open the joystick device following the usual semantics (that is, with open).
 Since the driver now reports events instead of polling for changes,
 immediately after the open it will issue a series of synthetic events
-(JS_EVENT_INIT) that you can read to check the initial state of the
+(JS_EVENT_INIT) that you can read to obtain the initial state of the
 joystick.
 
 By default, the device is opened in blocking mode::
@@ -182,7 +202,7 @@ the actual state of the joystick.
 
 .. note::
 
- As for version 1.2.8, the queue is circular and able to hold 64
+ As of version 1.2.8, the queue is circular and able to hold 64
  events. You can increment this size bumping up JS_BUFF_SIZE in
  joystick.h and recompiling the driver.
 
diff --git a/Documentation/input/joystick.rst b/Documentation/input/joydev/joystick.rst
similarity index 86%
rename from Documentation/input/joystick.rst
rename to Documentation/input/joydev/joystick.rst
index c9c175ffc2ff..b90705eb69b1 100644
--- a/Documentation/input/joystick.rst
+++ b/Documentation/input/joydev/joystick.rst
@@ -1,56 +1,17 @@
 .. include:: <isonum.txt>
 
-============================
-Linux Joystick driver v2.0.0
-============================
-
-:Copyright: |copy| 1996-2000 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE
-
-
-Disclaimer
-==========
-
-This program is free software; you can redistribute it and/or modify it
-under the terms of the GNU General Public License as published by the Free
-Software Foundation; either version 2 of the License, or (at your option)
-any later version.
-
-This program is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
-or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
-more details.
-
-You should have received a copy of the GNU General Public License along
-with this program; if not, write to the Free Software Foundation, Inc., 59
-Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
-Should you need to contact me, the author, you can do so either by e-mail
-- mail your message to <vojtech@ucw.cz>, or by paper mail: Vojtech Pavlik,
-Simunkova 1594, Prague 8, 182 00 Czech Republic
-
-For your convenience, the GNU General Public License version 2 is included
-in the package: See the file COPYING.
-
-Intro
-=====
+Introduction
+============
 
 The joystick driver for Linux provides support for a variety of joysticks
 and similar devices. It is based on a larger project aiming to support all
 input devices in Linux.
 
-Should you encounter any problems while using the driver, or joysticks
-this driver can't make complete use of, I'm very interested in hearing about
-them. Bug reports and success stories are also welcome.
-
-The input project website is at:
-
-	http://atrey.karlin.mff.cuni.cz/~vojtech/input/
-
-There is also a mailing list for the driver at:
+The mailing list for the project is:
 
-	listproc@atrey.karlin.mff.cuni.cz
+	linux-input@vger.kernel.org
 
-send "subscribe linux-joystick Your Name" to subscribe to it.
+send "subscribe linux-input" to majordomo@vger.kernel.org to subscribe to it.
 
 Usage
 =====
@@ -58,18 +19,22 @@ Usage
 For basic usage you just choose the right options in kernel config and
 you should be set.
 
-inpututils
-----------
+Utilities
+---------
 
-For testing and other purposes (for example serial devices), a set of
-utilities is available at the abovementioned website. I suggest you download
-and install it before going on.
+For testing and other purposes (for example serial devices), there is a set
+of utilities, such as ``jstest``, ``jscal``, and ``evtest``,
+usually packaged as ``joystick``, ``input-utils``, ``evtest``, and so on.
+
+``inputattach`` utility is required if your joystick is connected to a
+serial port.
 
 Device nodes
 ------------
 
-For applications to be able to use the joysticks,
-you'll have to manually create these nodes in /dev::
+For applications to be able to use the joysticks, device nodes should be
+created in /dev. Normally it is done automatically by the system, but
+it can also be done by hand::
 
     cd /dev
     rm js*
@@ -166,7 +131,6 @@ And add a line to your rc script executing that file::
 This way, after the next reboot your joystick will remain calibrated. You
 can also add the ``jscal -p`` line to your shutdown script.
 
-
 HW specific driver information
 ==============================
 
@@ -467,6 +431,10 @@ future if I get an Amiga in the reach of my fingers.
 Game console and 8-bit pads and joysticks
 -----------------------------------------
 
+These pads and joysticks are not designed for PCs and other computers
+Linux runs on, and usually require a special connector for attaching
+them through a parallel port.
+
 See :ref:`joystick-parport` for more info.
 
 SpaceTec/LabTec devices
@@ -613,19 +581,3 @@ FAQ
 :Q: My joystick doesn't work with Quake / Quake 2. What's the cause?
 :A: Quake / Quake 2 don't support joystick. Use joy2key to simulate keypresses
     for them.
-
-Programming Interface
-=====================
-
-The 1.0 driver uses a new, event based approach to the joystick driver.
-Instead of the user program polling for the joystick values, the joystick
-driver now reports only any changes of its state. See joystick-api.txt,
-joystick.h and jstest.c included in the joystick package for more
-information. The joystick device can be used in either blocking or
-nonblocking mode and supports select() calls.
-
-For backward compatibility the old (v0.x) interface is still included.
-Any call to the joystick driver using the old interface will return values
-that are compatible to the old interface.  This interface is still limited
-to 2 axes, and applications using it usually decode only 2 buttons, although
-the driver provides up to 32.
diff --git a/Documentation/input/joystick-parport.rst b/Documentation/input/joystick-parport.rst
index fa8cab584793..cc2ab871e701 100644
--- a/Documentation/input/joystick-parport.rst
+++ b/Documentation/input/joystick-parport.rst
@@ -2,9 +2,9 @@
 
 .. _joystick-parport:
 
-===================================
-Linux Joystick parport drivers v2.0
-===================================
+==============================
+Parallel port Joystick Drivers
+==============================
 
 :Copyright: |copy| 1998-2000 Vojtech Pavlik <vojtech@ucw.cz>
 :Copyright: |copy| 1998 Andree Borrmann <a.borrmann@tu-bs.de>
@@ -20,8 +20,8 @@ it will be true. So, use it at your own risk. The possible damages that can
 happen include burning your parallel port, and/or the sticks and joystick
 and maybe even more. Like when a lightning kills you it is not our problem.
 
-Intro
-=====
+Introduction
+============
 
 The joystick parport drivers are used for joysticks and gamepads not
 originally designed for PCs and other computers Linux runs on. Because of
@@ -582,7 +582,7 @@ use turbografx.map2 and turbografx.map3 as additional command line parameters
 for two more interfaces.
 
 PC parallel port pinout
------------------------
+=======================
 
 ::
 
-- 
2.12.2.762.g0e3151a226-goog

[PATCH 6/8] Input: docs - note that MT-A protocol is obsolete

[Dmitry Torokhov]

Everyone should be using multitouch protocol B (slotted) now.

Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
---
 Documentation/input/multi-touch-protocol.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst
index 81775d7c1997..8035868c56bc 100644
--- a/Documentation/input/multi-touch-protocol.rst
+++ b/Documentation/input/multi-touch-protocol.rst
@@ -22,6 +22,9 @@ describes how to send the raw data for all contacts to the receiver. For
 devices capable of tracking identifiable contacts (type B), the protocol
 describes how to send updates for individual contacts via event slots.
 
+.. note::
+   MT potocol type A is obsolete, all kernel drivers have been
+   converted to use type B.
 
 Protocol Usage
 --------------
@@ -400,9 +403,6 @@ in a finger packet must not be recognized as single-touch events.
 For type A devices, all finger data bypasses input filtering, since
 subsequent events of the same type refer to different fingers.
 
-For example usage of the type A protocol, see the bcm5974 driver. For
-example usage of the type B protocol, see the hid-egalax driver.
-
 .. [#f1] Also, the difference (TOOL_X - POSITION_X) can be used to model tilt.
 .. [#f2] The list can of course be extended.
 .. [#f3] The mtdev project: http://bitmath.org/code/mtdev/.
-- 
2.12.2.762.g0e3151a226-goog

[PATCH 7/8] Input: docs - split input docs into kernel- and user-facing

[Dmitry Torokhov]

Split input documentation into several groups: kernel- and user-facing, and
notes about individual device drivers. Move device drivers docs into a
separate subdirectory.

Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
---
 Documentation/input/{ => devices}/alps.rst         |  2 +-
 Documentation/input/{ => devices}/amijoy.rst       |  0
 Documentation/input/{ => devices}/appletouch.rst   |  0
 Documentation/input/{ => devices}/atarikbd.rst     |  0
 Documentation/input/{ => devices}/bcm5974.rst      |  0
 Documentation/input/{ => devices}/cma3000_d0x.rst  |  4 +-
 Documentation/input/{ => devices}/cs461x.rst       |  8 +---
 Documentation/input/{ => devices}/edt-ft5x06.rst   |  0
 Documentation/input/{ => devices}/elantech.rst     |  0
 Documentation/input/{ => devices}/gpio-tilt.rst    |  8 ++--
 .../input/{ => devices}/iforce-protocol.rst        |  0
 Documentation/input/devices/index.rst              | 19 +++++++++
 .../input/{ => devices}/joystick-parport.rst       |  2 +-
 Documentation/input/{ => devices}/ntrig.rst        |  0
 .../input/{ => devices}/rotary-encoder.rst         |  0
 Documentation/input/{ => devices}/sentelic.rst     | 10 ++---
 Documentation/input/{ => devices}/walkera0701.rst  |  0
 Documentation/input/{ => devices}/xpad.rst         | 22 +++++-----
 Documentation/input/{ => devices}/yealink.rst      | 47 ++++++++--------------
 Documentation/input/gamepad.rst                    | 10 ++---
 Documentation/input/index.rst                      | 39 ++----------------
 Documentation/input/input-programming.rst          |  5 +--
 Documentation/input/input_kapi.rst                 | 17 ++++++++
 Documentation/input/input_uapi.rst                 | 21 ++++++++++
 24 files changed, 107 insertions(+), 107 deletions(-)
 rename Documentation/input/{ => devices}/alps.rst (99%)
 rename Documentation/input/{ => devices}/amijoy.rst (100%)
 rename Documentation/input/{ => devices}/appletouch.rst (100%)
 rename Documentation/input/{ => devices}/atarikbd.rst (100%)
 rename Documentation/input/{ => devices}/bcm5974.rst (100%)
 rename Documentation/input/{ => devices}/cma3000_d0x.rst (97%)
 rename Documentation/input/{ => devices}/cs461x.rst (88%)
 rename Documentation/input/{ => devices}/edt-ft5x06.rst (100%)
 rename Documentation/input/{ => devices}/elantech.rst (100%)
 rename Documentation/input/{ => devices}/gpio-tilt.rst (98%)
 rename Documentation/input/{ => devices}/iforce-protocol.rst (100%)
 create mode 100644 Documentation/input/devices/index.rst
 rename Documentation/input/{ => devices}/joystick-parport.rst (99%)
 rename Documentation/input/{ => devices}/ntrig.rst (100%)
 rename Documentation/input/{ => devices}/rotary-encoder.rst (100%)
 rename Documentation/input/{ => devices}/sentelic.rst (99%)
 rename Documentation/input/{ => devices}/walkera0701.rst (100%)
 rename Documentation/input/{ => devices}/xpad.rst (95%)
 rename Documentation/input/{ => devices}/yealink.rst (94%)
 create mode 100644 Documentation/input/input_kapi.rst
 create mode 100644 Documentation/input/input_uapi.rst

diff --git a/Documentation/input/alps.rst b/Documentation/input/devices/alps.rst
similarity index 99%
rename from Documentation/input/alps.rst
rename to Documentation/input/devices/alps.rst
index 76a71a146e50..6779148e428c 100644
--- a/Documentation/input/alps.rst
+++ b/Documentation/input/devices/alps.rst
@@ -5,7 +5,7 @@ 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
diff --git a/Documentation/input/amijoy.rst b/Documentation/input/devices/amijoy.rst
similarity index 100%
rename from Documentation/input/amijoy.rst
rename to Documentation/input/devices/amijoy.rst
diff --git a/Documentation/input/appletouch.rst b/Documentation/input/devices/appletouch.rst
similarity index 100%
rename from Documentation/input/appletouch.rst
rename to Documentation/input/devices/appletouch.rst
diff --git a/Documentation/input/atarikbd.rst b/Documentation/input/devices/atarikbd.rst
similarity index 100%
rename from Documentation/input/atarikbd.rst
rename to Documentation/input/devices/atarikbd.rst
diff --git a/Documentation/input/bcm5974.rst b/Documentation/input/devices/bcm5974.rst
similarity index 100%
rename from Documentation/input/bcm5974.rst
rename to Documentation/input/devices/bcm5974.rst
diff --git a/Documentation/input/cma3000_d0x.rst b/Documentation/input/devices/cma3000_d0x.rst
similarity index 97%
rename from Documentation/input/cma3000_d0x.rst
rename to Documentation/input/devices/cma3000_d0x.rst
index 6f40c17c1aca..8bc8e61487b0 100644
--- a/Documentation/input/cma3000_d0x.rst
+++ b/Documentation/input/devices/cma3000_d0x.rst
@@ -1,5 +1,5 @@
-Kernel driver for CMA3000-D0x
-=============================
+CMA3000-D0x Accelerometer
+=========================
 
 Supported chips:
 * VTI CMA3000-D0x
diff --git a/Documentation/input/cs461x.rst b/Documentation/input/devices/cs461x.rst
similarity index 88%
rename from Documentation/input/cs461x.rst
rename to Documentation/input/devices/cs461x.rst
index 1450436dcc9e..b1e6d508ad26 100644
--- a/Documentation/input/cs461x.rst
+++ b/Documentation/input/devices/cs461x.rst
@@ -1,9 +1,6 @@
 Crystal SoundFusion CS4610/CS4612/CS461 joystick
 ================================================
 
-Preface
--------
-
 This is a new low-level driver to support analog joystick attached to
 Crystal SoundFusion CS4610/CS4612/CS4615. This code is based upon
 Vortex/Solo drivers as an example of decoration style, and ALSA
@@ -25,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.
diff --git a/Documentation/input/edt-ft5x06.rst b/Documentation/input/devices/edt-ft5x06.rst
similarity index 100%
rename from Documentation/input/edt-ft5x06.rst
rename to Documentation/input/devices/edt-ft5x06.rst
diff --git a/Documentation/input/elantech.rst b/Documentation/input/devices/elantech.rst
similarity index 100%
rename from Documentation/input/elantech.rst
rename to Documentation/input/devices/elantech.rst
diff --git a/Documentation/input/gpio-tilt.rst b/Documentation/input/devices/gpio-tilt.rst
similarity index 98%
rename from Documentation/input/gpio-tilt.rst
rename to Documentation/input/devices/gpio-tilt.rst
index 23de9eff6a34..fa6e64570aa7 100644
--- a/Documentation/input/gpio-tilt.rst
+++ b/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,8 +24,8 @@ 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::
diff --git a/Documentation/input/iforce-protocol.rst b/Documentation/input/devices/iforce-protocol.rst
similarity index 100%
rename from Documentation/input/iforce-protocol.rst
rename to Documentation/input/devices/iforce-protocol.rst
diff --git a/Documentation/input/devices/index.rst b/Documentation/input/devices/index.rst
new file mode 100644
index 000000000000..95a453782bad
--- /dev/null
+++ b/Documentation/input/devices/index.rst
@@ -0,0 +1,19 @@
+Driver-specific documentation
+=============================
+
+This section provides information about various devices supported by the
+Linux kernel, their protocols, and driver details.
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+   :glob:
+
+   *
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/input/joystick-parport.rst b/Documentation/input/devices/joystick-parport.rst
similarity index 99%
rename from Documentation/input/joystick-parport.rst
rename to Documentation/input/devices/joystick-parport.rst
index cc2ab871e701..e8ce16ee799a 100644
--- a/Documentation/input/joystick-parport.rst
+++ b/Documentation/input/devices/joystick-parport.rst
@@ -3,7 +3,7 @@
 .. _joystick-parport:
 
 ==============================
-Parallel port Joystick Drivers
+Parallel Port Joystick Drivers
 ==============================
 
 :Copyright: |copy| 1998-2000 Vojtech Pavlik <vojtech@ucw.cz>
diff --git a/Documentation/input/ntrig.rst b/Documentation/input/devices/ntrig.rst
similarity index 100%
rename from Documentation/input/ntrig.rst
rename to Documentation/input/devices/ntrig.rst
diff --git a/Documentation/input/rotary-encoder.rst b/Documentation/input/devices/rotary-encoder.rst
similarity index 100%
rename from Documentation/input/rotary-encoder.rst
rename to Documentation/input/devices/rotary-encoder.rst
diff --git a/Documentation/input/sentelic.rst b/Documentation/input/devices/sentelic.rst
similarity index 99%
rename from Documentation/input/sentelic.rst
rename to Documentation/input/devices/sentelic.rst
index d1a476f973b1..1b6829b74ae8 100644
--- a/Documentation/input/sentelic.rst
+++ b/Documentation/input/devices/sentelic.rst
@@ -1,16 +1,16 @@
 .. include:: <isonum.txt>
 
-===============
-Sentelic Driver
-===============
+=================
+Sentelic Touchpad
+=================
 
 
 :Copyright: |copy| 2002-2011 Sentelic Corporation.
 
 :Last update: Dec-07-2011
 
-Finger Sensing Pad Intellimouse Mode(scrolling wheel, 4th and 5th buttons)
-==========================================================================
+Finger Sensing Pad Intellimouse Modei (scrolling wheel, 4th and 5th buttons)
+============================================================================
 
 A) MSID 4: Scrolling wheel mode plus Forward page(4th button) and Backward
    page (5th button)
diff --git a/Documentation/input/walkera0701.rst b/Documentation/input/devices/walkera0701.rst
similarity index 100%
rename from Documentation/input/walkera0701.rst
rename to Documentation/input/devices/walkera0701.rst
diff --git a/Documentation/input/xpad.rst b/Documentation/input/devices/xpad.rst
similarity index 95%
rename from Documentation/input/xpad.rst
rename to Documentation/input/devices/xpad.rst
index 0bae002cf17a..80028433b460 100644
--- a/Documentation/input/xpad.rst
+++ b/Documentation/input/devices/xpad.rst
@@ -125,7 +125,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,
@@ -138,7 +138,7 @@ 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].
+/proc/bus/usb/devices. There should be an entry like the one at the end [4]_.
 
 
 
@@ -199,13 +199,12 @@ the basic functionality.
 References
 ==========
 
-[1]: http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
+.. [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):
 
-[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
@@ -214,8 +213,9 @@ References
     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):
 
-[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
@@ -225,9 +225,7 @@ References
     I:  If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad
     E:  Ad=82(I) Atr=03(Int.) MxPS=  32 Ivl=4ms
     E:  Ad=02(O) Atr=03(Int.) MxPS=  32 Ivl=4ms
-
-[6]: http://lxr.free-electrons.com/ident?i=xpad_device
-
+.. [6] http://lxr.free-electrons.com/ident?i=xpad_device
 
 
 Historic Edits
diff --git a/Documentation/input/yealink.rst b/Documentation/input/devices/yealink.rst
similarity index 94%
rename from Documentation/input/yealink.rst
rename to Documentation/input/devices/yealink.rst
index b231d8baf4bb..bb5a1aafeca2 100644
--- a/Documentation/input/yealink.rst
+++ b/Documentation/input/devices/yealink.rst
@@ -18,36 +18,6 @@ The p1k is a relatively cheap usb 1.1 phone with:
 For vendor documentation see http://www.yealink.com
 
 
-Compilation (stand alone version)
-=================================
-
-Currently only kernel 2.6.x.y versions are supported.
-In order to build the yealink.ko module do::
-
-  make
-
-If you encounter problems please check if in the MAKE_OPTS variable in
-the Makefile is pointing to the location where your kernel sources
-are located, default /usr/src/linux.
-
-
-Troubleshooting
-~~~~~~~~~~~~~~~
-
-:Q: Module yealink compiled and installed without any problem but phone
-    is not initialized and does not react to any actions.
-:A: If you see something like:
-    hiddev0: USB HID v1.00 Device [Yealink Network Technology Ltd. VOIP USB Phone
-    in dmesg, it means that the hid driver has grabbed the device first. Try to
-    load module yealink before any other usb hid driver. Please see the
-    instructions provided by your distribution on module configuration.
-
-:Q: Phone is working now (displays version and accepts keypad input) but I can't
-    find the sysfs files.
-:A: The sysfs files are located on the particular usb endpoint. On most
-    distributions you can do: "find /sys/ -name get_icons" for a hint.
-
-
 keyboard features
 =================
 
@@ -229,6 +199,23 @@ limit of the device.
     aplay foobar.wav
 
 
+Troubleshooting
+===============
+
+:Q: Module yealink compiled and installed without any problem but phone
+    is not initialized and does not react to any actions.
+:A: If you see something like:
+    hiddev0: USB HID v1.00 Device [Yealink Network Technology Ltd. VOIP USB Phone
+    in dmesg, it means that the hid driver has grabbed the device first. Try to
+    load module yealink before any other usb hid driver. Please see the
+    instructions provided by your distribution on module configuration.
+
+:Q: Phone is working now (displays version and accepts keypad input) but I can't
+    find the sysfs files.
+:A: The sysfs files are located on the particular usb endpoint. On most
+    distributions you can do: "find /sys/ -name get_icons" for a hint.
+
+
 Credits & Acknowledgments
 =========================
 
diff --git a/Documentation/input/gamepad.rst b/Documentation/input/gamepad.rst
index 1bc4555c0ccb..4d5e7fb80a84 100644
--- a/Documentation/input/gamepad.rst
+++ b/Documentation/input/gamepad.rst
@@ -1,12 +1,12 @@
------------------
-Linux Gamepad API
------------------
+---------------------------
+Linux Gamepad Specification
+---------------------------
 
 :Author: 2013 by David Herrmann <dh.herrmann@gmail.com>
 
 
-Intro
-~~~~~
+Introduction
+~~~~~~~~~~~~
 Linux provides many different input drivers for gamepad hardware. To avoid
 having user-space deal with different button-mappings for each gamepad, this
 document defines how gamepads are supposed to report their data.
diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst
index b25a67198a65..7a3e71c2bd00 100644
--- a/Documentation/input/index.rst
+++ b/Documentation/input/index.rst
@@ -8,42 +8,9 @@ Contents:
    :maxdepth: 2
    :numbered:
 
-   input
-   input-programming
-   event-codes
-   joydev/index
-   multi-touch-protocol
-   gamepad
-   gameport-programming
-   ff
-   notifier
-   userio
-
-Input drivers
-=============
-
-.. toctree::
-   :maxdepth: 2
-   :numbered:
-
-   alps
-   amijoy
-   appletouch
-   atarikbd
-   bcm5974
-   cma3000_d0x
-   cs461x
-   edt-ft5x06
-   elantech
-   iforce-protocol
-   joystick-parport
-   gpio-tilt
-   ntrig
-   rotary-encoder
-   sentelic
-   walkera0701
-   xpad
-   yealink
+   input_uapi
+   input_kapi
+   devices/index
 
 .. only::  subproject and html
 
diff --git a/Documentation/input/input-programming.rst b/Documentation/input/input-programming.rst
index 4d3b22222e93..57dbab652cfa 100644
--- a/Documentation/input/input-programming.rst
+++ b/Documentation/input/input-programming.rst
@@ -1,7 +1,4 @@
-~~~~~~~~~~~~~~~~~~~~~~~~~
-Programming input drivers
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
+===============================
 Creating an input device driver
 ===============================
 
diff --git a/Documentation/input/input_kapi.rst b/Documentation/input/input_kapi.rst
new file mode 100644
index 000000000000..41f1b7e6b78e
--- /dev/null
+++ b/Documentation/input/input_kapi.rst
@@ -0,0 +1,17 @@
+.. include:: <isonum.txt>
+
+################################
+Linux Input Subsystem kernel API
+################################
+
+.. class:: toc-title
+
+        Table of Contents
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   input-programming
+   gameport-programming
+   notifier
diff --git a/Documentation/input/input_uapi.rst b/Documentation/input/input_uapi.rst
new file mode 100644
index 000000000000..12ef8974a773
--- /dev/null
+++ b/Documentation/input/input_uapi.rst
@@ -0,0 +1,21 @@
+.. include:: <isonum.txt>
+
+###################################
+Linux Input Subsystem userspace API
+###################################
+
+.. class:: toc-title
+
+        Table of Contents
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   input
+   event-codes
+   multi-touch-protocol
+   gamepad
+   ff
+   joydev/index
+   userio
-- 
2.12.2.762.g0e3151a226-goog

[PATCH 8/8] Input: docs - freshen up introduction

[Dmitry Torokhov]

Stop saying that API is experimental and that only USB is supported,
acknowledge that evdev is the preferred interface, and remove paragraph
encouraging people sending snail mail to Vojtech :) along with his email.

Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
---
 Documentation/input/event-codes.rst         |   2 +
 Documentation/input/input.rst               | 253 +++++++++++++---------------
 Documentation/input/joydev/joystick-api.rst |   2 +
 Documentation/input/joydev/joystick.rst     |   2 +
 4 files changed, 127 insertions(+), 132 deletions(-)

diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst
index 92db50954169..00b88f113bda 100644
--- a/Documentation/input/event-codes.rst
+++ b/Documentation/input/event-codes.rst
@@ -1,3 +1,5 @@
+.. _input-event-codes:
+
 =================
 Input event codes
 =================
diff --git a/Documentation/input/input.rst b/Documentation/input/input.rst
index ac7669ad3e76..3b3a22975106 100644
--- a/Documentation/input/input.rst
+++ b/Documentation/input/input.rst
@@ -1,25 +1,20 @@
 .. include:: <isonum.txt>
 
-===================
-Linux Input drivers
-===================
+============
+Introduction
+============
 
 :Copyright: |copy| 1999-2001 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE
 
-Should you need to contact me, the author, you can do so either by e-mail
-- mail your message to <vojtech@ucw.cz>, or by paper mail: Vojtech Pavlik,
-Simunkova 1594, Prague 8, 182 00 Czech Republic
-
-Introduction
+Architecture
 ============
 
-This is a collection of drivers that is designed to support all input
-devices under Linux. While it is currently used only on for USB input
-devices, future use (say 2.5/2.6) is expected to expand to replace
-most of the existing input system, which is why it lives in
-drivers/input/ instead of drivers/usb/.
+Input subsystem  a collection of drivers that is designed to support
+all input devices under Linux. Most of the drivers reside in
+drivers/input, although quite a few live in drivers/hid and
+drivers/platform.
 
-The centre of the input drivers is the input module, which must be
+The core of the input subsystem is the input module, which must be
 loaded before any other of the input modules - it serves as a way of
 communication between two groups of modules:
 
@@ -32,9 +27,9 @@ events (keystrokes, mouse movements) to the input module.
 Event handlers
 --------------
 
-These modules get events from input and pass them where needed via
-various interfaces - keystrokes to the kernel, mouse movements via a
-simulated PS/2 interface to GPM and X and so on.
+These modules get events from input core and pass them where needed
+via various interfaces - keystrokes to the kernel, mouse movements via
+a simulated PS/2 interface to GPM and X, and so on.
 
 Simple Usage
 ============
@@ -45,19 +40,18 @@ kernel)::
 
 	input
 	mousedev
-	keybdev
 	usbcore
 	uhci_hcd or ohci_hcd or ehci_hcd
 	usbhid
+	hid_generic
 
 After this, the USB keyboard will work straight away, and the USB mouse
 will be available as a character device on major 13, minor 63::
 
 	crw-r--r--   1 root     root      13,  63 Mar 28 22:45 mice
 
-This device has to be created.
-
-The commands to create it by hand are::
+This device usually created automatically by the system. The commands
+to create it by hand are::
 
 	cd /dev
 	mkdir input
@@ -81,100 +75,50 @@ When you do all of the above, you can use your USB mouse and keyboard.
 Detailed Description
 ====================
 
-Device drivers
+Event handlers
 --------------
 
-Device drivers are the modules that generate events. The events are
-however not useful without being handled, so you also will need to use some
-of the modules from section 3.2.
-
-usbhid
-~~~~~~
-
-usbhid is the largest and most complex driver of the whole suite. It
-handles all HID devices, and because there is a very wide variety of them,
-and because the USB HID specification isn't simple, it needs to be this big.
-
-Currently, it handles USB mice, joysticks, gamepads, steering wheels
-keyboards, trackballs and digitizers.
-
-However, USB uses HID also for monitor controls, speaker controls, UPSs,
-LCDs and many other purposes.
-
-The monitor and speaker controls should be easy to add to the hid/input
-interface, but for the UPSs and LCDs it doesn't make much sense. For this,
-the hiddev interface was designed. See Documentation/hid/hiddev.txt
-for more information about it.
-
-The usage of the usbhid module is very simple, it takes no parameters,
-detects everything automatically and when a HID device is inserted, it
-detects it appropriately.
-
-However, because the devices vary wildly, you might happen to have a
-device that doesn't work well. In that case #define DEBUG at the beginning
-of hid-core.c and send me the syslog traces.
+Event handlers distribute the events from the devices to userspace and
+in-kernel consumers, as needed.
 
-usbmouse
-~~~~~~~~
-
-For embedded systems, for mice with broken HID descriptors and just any
-other use when the big usbhid wouldn't be a good choice, there is the
-usbmouse driver. It handles USB mice only. It uses a simpler HIDBP
-protocol. This also means the mice must support this simpler protocol. Not
-all do. If you don't have any strong reason to use this module, use usbhid
-instead.
-
-usbkbd
-~~~~~~
-
-Much like usbmouse, this module talks to keyboards with a simplified
-HIDBP protocol. It's smaller, but doesn't support any extra special keys.
-Use usbhid instead if there isn't any special reason to use this.
-
-wacom
+evdev
 ~~~~~
 
-This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom
-PenPartner, that one is handled by the HID driver. Although the Intuos and
-Graphire tablets claim that they are HID tablets as well, they are not and
-thus need this specific driver.
+``evdev`` is the generic input event interface. It passes the events
+generated in the kernel straight to the program, with timestamps. The
+event codes are the same on all architectures and are hardware
+independent.
 
-iforce
-~~~~~~
+This is the preferred interface for userspace to consume user
+input, and all clients are encouraged to use it.
 
-A driver for I-Force joysticks and wheels, both over USB and RS232.
-It includes ForceFeedback support now, even though Immersion
-Corp. considers the protocol a trade secret and won't disclose a word
-about it.
+See :ref:`event-interface` for notes on API.
 
-Event handlers
---------------
+The devices are in /dev/input::
 
-Event handlers distribute the events from the devices to userland and
-kernel, as needed.
+	crw-r--r--   1 root     root      13,  64 Apr  1 10:49 event0
+	crw-r--r--   1 root     root      13,  65 Apr  1 10:50 event1
+	crw-r--r--   1 root     root      13,  66 Apr  1 10:50 event2
+	crw-r--r--   1 root     root      13,  67 Apr  1 10:50 event3
+	...
 
-keybdev
-~~~~~~~
+There are two ranges of minors: 64 through 95 is the static legacy
+range. If there are more than 32 input devices in a system, additional
+evdev nodes are created with minors starting with 256.
 
-keybdev is currently a rather ugly hack that translates the input
-events into architecture-specific keyboard raw mode (Xlated AT Set2 on
-x86), and passes them into the handle_scancode function of the
-keyboard.c module. This works well enough on all architectures that
-keybdev can generate rawmode on, other architectures can be added to
-it.
+keyboard
+~~~~~~~~
 
-The right way would be to pass the events to keyboard.c directly,
-best if keyboard.c would itself be an event handler. This is done in
-the input patch, available on the webpage mentioned below.
+``keyboard`` is in-kernel input handler ad is a part of VT code. It
+consumes keyboard keystrokes and handles user input for VT consoles.
 
 mousedev
 ~~~~~~~~
 
-mousedev is also a hack to make programs that use mouse input
+``mousedev`` is a hack to make legacy programs that use mouse input
 work. It takes events from either mice or digitizers/tablets and makes
 a PS/2-style (a la /dev/psaux) mouse device available to the
-userland. Ideally, the programs could use a more reasonable interface,
-for example evdev
+userland.
 
 Mousedev devices in /dev/input (as shown above) are::
 
@@ -190,8 +134,9 @@ Mousedev devices in /dev/input (as shown above) are::
 Each ``mouse`` device is assigned to a single mouse or digitizer, except
 the last one - ``mice``. This single character device is shared by all
 mice and digitizers, and even if none are connected, the device is
-present.  This is useful for hotplugging USB mice, so that programs
-can open the device even when no mice are present.
+present.  This is useful for hotplugging USB mice, so that older programs
+that do not handle hotplug can open the device even when no mice are
+present.
 
 CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
 the size of your screen (in pixels) in XFree86. This is needed if you
@@ -208,11 +153,10 @@ mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons.
 joydev
 ~~~~~~
 
-Joydev implements v0.x and v1.x Linux joystick api, much like
-drivers/char/joystick/joystick.c used to in earlier versions. See
-joystick-api.txt in the Documentation subdirectory for details.  As
-soon as any joystick is connected, it can be accessed in /dev/input
-on::
+``joydev`` implements v0.x and v1.x Linux joystick API. See
+:ref:`joystick-api` for details.
+
+As soon as any joystick is connected, it can be accessed in /dev/input on::
 
 	crw-r--r--   1 root     root      13,   0 Apr  1 10:50 js0
 	crw-r--r--   1 root     root      13,   1 Apr  1 10:50 js1
@@ -220,56 +164,99 @@ on::
 	crw-r--r--   1 root     root      13,   3 Apr  1 10:50 js3
 	...
 
-And so on up to js31.
+And so on up to js31 in legacy range, and additional nodes with minors
+above 256 if there are more joystick devices.
 
-evdev
-~~~~~
+Device drivers
+--------------
 
-evdev is the generic input event interface. It passes the events
-generated in the kernel straight to the program, with timestamps. The
-API is still evolving, but should be usable now. It's described in
-section 5.
+Device drivers are the modules that generate events.
 
-This should be the way for GPM and X to get keyboard and mouse
-events. It allows for multihead in X without any specific multihead
-kernel support. The event codes are the same on all architectures and
-are hardware independent.
+hid-generic
+~~~~~~~~~~~
 
-The devices are in /dev/input::
+``hid-generic`` is one of the largest and most complex driver of the
+whole suite. It handles all HID devices, and because there is a very
+wide variety of them, and because the USB HID specification isn't
+simple, it needs to be this big.
 
-	crw-r--r--   1 root     root      13,  64 Apr  1 10:49 event0
-	crw-r--r--   1 root     root      13,  65 Apr  1 10:50 event1
-	crw-r--r--   1 root     root      13,  66 Apr  1 10:50 event2
-	crw-r--r--   1 root     root      13,  67 Apr  1 10:50 event3
-	...
+Currently, it handles USB mice, joysticks, gamepads, steering wheels
+keyboards, trackballs and digitizers.
+
+However, USB uses HID also for monitor controls, speaker controls, UPSs,
+LCDs and many other purposes.
+
+The monitor and speaker controls should be easy to add to the hid/input
+interface, but for the UPSs and LCDs it doesn't make much sense. For this,
+the hiddev interface was designed. See Documentation/hid/hiddev.txt
+for more information about it.
+
+The usage of the usbhid module is very simple, it takes no parameters,
+detects everything automatically and when a HID device is inserted, it
+detects it appropriately.
 
-And so on up to event31.
+However, because the devices vary wildly, you might happen to have a
+device that doesn't work well. In that case #define DEBUG at the beginning
+of hid-core.c and send me the syslog traces.
+
+usbmouse
+~~~~~~~~
+
+For embedded systems, for mice with broken HID descriptors and just any
+other use when the big usbhid wouldn't be a good choice, there is the
+usbmouse driver. It handles USB mice only. It uses a simpler HIDBP
+protocol. This also means the mice must support this simpler protocol. Not
+all do. If you don't have any strong reason to use this module, use usbhid
+instead.
+
+usbkbd
+~~~~~~
+
+Much like usbmouse, this module talks to keyboards with a simplified
+HIDBP protocol. It's smaller, but doesn't support any extra special keys.
+Use usbhid instead if there isn't any special reason to use this.
+
+psmouse
+~~~~~~~
+
+This is driver for all flavors of pointing devices using PS/2
+protocol, including Synaptics and ALPS touchpads, Intellimouse
+Explorer devices, Logitech PS/2 mice and so on.
+
+atkbd
+~~~~~
+
+This is driver for PS/2 (AT) keyboards.
+
+iforce
+~~~~~~
+
+A driver for I-Force joysticks and wheels, both over USB and RS232.
+It includes Force Feedback support now, even though Immersion
+Corp. considers the protocol a trade secret and won't disclose a word
+about it.
 
 Verifying if it works
 =====================
 
 Typing a couple keys on the keyboard should be enough to check that
-a USB keyboard works and is correctly connected to the kernel keyboard
+a keyboard works and is correctly connected to the kernel keyboard
 driver.
 
 Doing a ``cat /dev/input/mouse0`` (c, 13, 32) will verify that a mouse
 is also emulated; characters should appear if you move it.
 
 You can test the joystick emulation with the ``jstest`` utility,
-available in the joystick package (see Documentation/input/joystick.txt).
+available in the joystick package (see :ref:`joystick-doc`).
 
-You can test the event devices with the ``evtest`` utility available
-in the LinuxConsole project CVS archive (see the URL below).
+You can test the event devices with the ``evtest`` utility.
+
+.. _event-interface:
 
 Event interface
 ===============
 
-Should you want to add event device support into any application (X, gpm,
-svgalib ...) I <vojtech@ucw.cz> will be happy to provide you any help I
-can. Here goes a description of the current state of things, which is going
-to be extended, but not changed incompatibly as time goes:
-
-You can use blocking and nonblocking reads, also select() on the
+You can use blocking and nonblocking reads, and also select() on the
 /dev/input/eventX devices, and you'll always get a whole number of input
 events on a read. Their layout is::
 
@@ -290,3 +277,5 @@ list is in include/uapi/linux/input-event-codes.h.
 ``value`` is the value the event carries. Either a relative change for
 EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
 release, 1 for keypress and 2 for autorepeat.
+
+See :ref:`input-event-codes` for more information about various even codes.
diff --git a/Documentation/input/joydev/joystick-api.rst b/Documentation/input/joydev/joystick-api.rst
index 42edcfc6e8af..95803e2e8cd0 100644
--- a/Documentation/input/joydev/joystick-api.rst
+++ b/Documentation/input/joydev/joystick-api.rst
@@ -1,3 +1,5 @@
+.. _joystick-api:
+
 =====================
 Programming Interface
 =====================
diff --git a/Documentation/input/joydev/joystick.rst b/Documentation/input/joydev/joystick.rst
index b90705eb69b1..9746fd76cc58 100644
--- a/Documentation/input/joydev/joystick.rst
+++ b/Documentation/input/joydev/joystick.rst
@@ -1,5 +1,7 @@
 .. include:: <isonum.txt>
 
+.. _joystick-doc:
+
 Introduction
 ============
 
-- 
2.12.2.762.g0e3151a226-goog

Re: [PATCH 7/8] Input: docs - split input docs into kernel- and user-facing

[Mauro Carvalho Chehab]

Hi Dmitry,

Em Sat, 15 Apr 2017 22:11:44 -0700
Dmitry Torokhov <dmitry.torokhov@gmail.com> escreveu:

> Split input documentation into several groups: kernel- and user-facing, and
> notes about individual device drivers. Move device drivers docs into a
> separate subdirectory.

I reviewed and tested Sphinx generation for this patch series.
Thinks are a way better organized now. Good work!

I got just a minor nitpick for HTML generation (see below).


However, building PDF documentation now hits an error, with Sphinx 1.4.9:

	Markup is unsupported in LaTeX:
	input/devices/xpad:209: literal blocks in footnotes are not supported by LaTeX

It seems it didn't like to have literal blocks inside footnotes:

	.. [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


I'll see if I can find a way to fix this issue.

There's something that, IMHO, would also fit better with the input
kAPI documentation, as it complements it:
	Documentation/driver-api/input.rst

It also makes sense to add, at the uAPI book, a:

	.. kernel-doc:: include/uapi/linux/input.h

In order for it to parse the kernel-doc tags there.

I'll prepare some RFC patches with it and see how well it goes.

Jon,

There's something that we need to think about it, and, perhaps
discuss on the next KS, with regards to how things will be better
organized, long term.

Before the ReST conversion, due to the way kernel-docs worked, all
documentation generated from the Kernel sources had to be under
Documentation/DocBook. At the end of the day, that forced that all
kAPI documentation generated from source files to be there.
In the case of drivers, most went to the driver-api book.

During the ReST conversion, when I converted the media documentation, you
pointed me that, on some time, we should be reorganizing the media
documentation, perhaps moving the uAPI documents to driver's API.

Now that we also converted the input documentation to ReST, I'm
seeing that, on other subsystems, there are also uAPI, kAPI and
driver-specific information grouped together.

So, I wonder what would be easier to maintain, long term, and
what would work best for the documentation readers.

I mean: assuming that we finish the ReST conversion, specially for
drivers, we'll end by having at leat 3 major groups of docs, for
every documented subsystem:
	- uAPI;
	- kAPI;
	- driver-specific documentation.

we have two options here:

1) have 3 huge documents:
	- driver-api;
	- driver-userspace-api;
	- driver-specific-docs.

If we would go to this patch, it probably makes sense to have one
sub-dir for each subsystem, e. g.:
	Documentation/driver-api/media
	Documentation/driver-userspace-api/media
	Documentation/driver-specific-docs/media
	Documentation/driver-api/input
	Documentation/driver-userspace-api/input
	Documentation/driver-specific-docs/input
	...

And, at maintainers file, for every subsystem:

MEDIA INPUT INFRASTRUCTURE (V4L/DVB)
...
	F:	Documentation/driver-api/media/
	F:	Documentation/driver-userspace-api/media/
	F:	Documentation/driver-specific-docs/media/

On a side note, just the media documentation, as of today,
generates a 1,000+ PDF book. I suspect that, if we'd go this
way, we'll generate really *huge* PDF files.


2) have one documentation per subsystem, just like the media
documentation is today.

Using my maintainer's hat, the difference from (1) or (2), is not
much: If we take approach (1), I would need to build 3 documents on
Sphinx to be sure that the documentation is OK; with (2), just one
document has everything, so it is easier to check if both PDF and
HTML outputs are fine. It will also build the documentation faster.

However, from the PoV of someone that it is writing a driver or
an userspace application to interact with some subsystem, it is
a way easier to have just one book that would describe such
subsystem, specially if they're using the PDF or ePUB books.

So, IMHO, (2) is better.

Regards,
Maur


> 
> Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>

> index d1a476f973b1..1b6829b74ae8 100644
> --- a/Documentation/input/sentelic.rst
> +++ b/Documentation/input/devices/sentelic.rst
> @@ -1,16 +1,16 @@
>  .. include:: <isonum.txt>
>  
> -===============
> -Sentelic Driver
> -===============
> +=================
> +Sentelic Touchpad
> +=================
>  
>  
>  :Copyright: |copy| 2002-2011 Sentelic Corporation.
>  
>  :Last update: Dec-07-2011
>  
> -Finger Sensing Pad Intellimouse Mode(scrolling wheel, 4th and 5th buttons)
> -==========================================================================
> +Finger Sensing Pad Intellimouse Modei (scrolling wheel, 4th and 5th buttons)
> +============================================================================

Nitpick: I guess there's a typo here:
		Modei -> Mode




Thanks,
Mauro

Re: [PATCH 7/8] Input: docs - split input docs into kernel- and user-facing

[Mauro Carvalho Chehab]

Em Sun, 16 Apr 2017 11:08:13 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> escreveu:

> Hi Dmitry,
> 
> Em Sat, 15 Apr 2017 22:11:44 -0700
> Dmitry Torokhov <dmitry.torokhov@gmail.com> escreveu:
> 
> > Split input documentation into several groups: kernel- and user-facing, and
> > notes about individual device drivers. Move device drivers docs into a
> > separate subdirectory.  
> 
> I reviewed and tested Sphinx generation for this patch series.
> Thinks are a way better organized now. Good work!
> 
> I got just a minor nitpick for HTML generation (see below).
> 
> 
> However, building PDF documentation now hits an error, with Sphinx 1.4.9:
> 
> 	Markup is unsupported in LaTeX:
> 	input/devices/xpad:209: literal blocks in footnotes are not supported by LaTeX
> 
> It seems it didn't like to have literal blocks inside footnotes:
> 
> 	.. [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
> 
> 
> I'll see if I can find a way to fix this issue.

The enclosed patch should fix it. It should come after the one that
replaces /proc/bus/usb/devices to /sys/kernel/debug/usb/devices.

It also fixes the last reference to the last URL.

Thanks,
Mauro