[PATCH v2 00/33] Convert input documentation to ReST

[PATCH v2 00/33] Convert input documentation to ReST

[Mauro Carvalho Chehab]

As I'm needing to touch some Input documentation, I took the time
to also convert the existing documents to ReST markup, building them
with Sphinx. The end result can be seen at:

   http://www.infradead.org/~mchehab/kernel_docs/input/

Instead of placing the documentation under Documentation/driver-api, I opted
to keep them at Documentation/input. The rationale is that the documentation
there doesn't have only driver-api bits, but other things too.

Those patches are based on the linux-input tree, on its next branch:
   git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input.git next

Please notice that I converted the two existing XFIG files there to SVG. As the
Documentation/sphinx/kfigure.py doesn't exist at the input tree, I opted
to use the ".. figure" tag to include the SVG files. This should be changed to
use the right extension, after merging upstream, but this should be a two line
patch that can be applied afterwards.

PS.: I didn't try to update the contents of the documentation int his series.

v2:
   - Rebased on current upstream, fixing a conflict at input.txt;
   - Added Peter Hutterer ack to event-codes.txt

Mauro Carvalho Chehab (33):
  docs: Documentation/input/input: convert it to ReST format
  docs: input/alps: convert it to ReST format
  docs: input/amijoy: convert it to ReST format
  docs: input/appletouch: convert it to ReST format
  docs: input/atarikbd: convert it to ReST format
  docs: input/bcm5974: convert it to ReST format
  docs: input/cd32: convert it to ReST format
  docs: input/cma3000_d0x: convert it to ReST format
  docs: input/cs461x: convert it to ReST format
  docs: input/elantech: convert it to ReST format
  docs: input/event-codes: convert it to ReST format
  docs: input/ff: convert it to ReST format
  docs: input/gamepad: convert it to ReST format
  docs: input/gameport-programming: convert it to ReST format
  docs: input/gpio-tilt: convert it to ReST format
  docs: input/iforce-protocol: convert it to ReST format
  docs: input/input-programming: convert it to ReST format
  docs: input/joystick-api: convert it to ReST format
  docs: input/joystick: convert it to ReST format
  docs: input/joystick-parport: convert it to ReST format
  docs: input/multi-touch-protocol: convert it to ReST format
  docs: input/notifier: convert it to ReST format
  docs: input/ntrig: convert it to ReST format
  docs: input/rotary-encoder: convert it to ReST format
  docs: input/sentelic: convert it to ReST format
  docs: input/userio: convert it to ReST format
  docs: input/walkera0701: convert it to ReST format
  docs: input/xpad: convert it to ReST format
  docs: input/yealink: convert it to ReST format
  docs-rst: create a book with Linux Input documentation
  docs: input/shape: convert it from xfig to svg
  docs: input/interactive: convert from xfig to svg
  docs: ff.rst: use svg files instead of xfig

 Documentation/conf.py                              |   2 +
 Documentation/input/{alps.txt => alps.rst}         |  43 +-
 Documentation/input/{amijoy.txt => amijoy.rst}     | 165 ++--
 .../input/{appletouch.txt => appletouch.rst}       |  33 +-
 Documentation/input/{atarikbd.txt => atarikbd.rst} | 214 +++--
 Documentation/input/{bcm5974.txt => bcm5974.rst}   |  43 +-
 Documentation/input/cd32.rst                       |  23 +
 Documentation/input/cd32.txt                       |  19 -
 .../input/{cma3000_d0x.txt => cma3000_d0x.rst}     |  72 +-
 Documentation/input/conf.py                        |  10 +
 Documentation/input/{cs461x.txt => cs461x.rst}     |  28 +-
 .../input/{edt-ft5x06.txt => edt-ft5x06.rst}       |   0
 Documentation/input/{elantech.txt => elantech.rst} | 306 +++----
 .../input/{event-codes.txt => event-codes.rst}     | 132 ++-
 Documentation/input/{ff.txt => ff.rst}             | 205 +++--
 Documentation/input/{gamepad.txt => gamepad.rst}   |  43 +-
 ...rt-programming.txt => gameport-programming.rst} |  83 +-
 Documentation/input/gpio-tilt.rst                  | 103 +++
 Documentation/input/gpio-tilt.txt                  | 103 ---
 Documentation/input/iforce-protocol.rst            | 381 +++++++++
 Documentation/input/iforce-protocol.txt            | 258 ------
 Documentation/input/index.rst                      |  77 ++
 ...input-programming.txt => input-programming.rst} | 253 +++---
 Documentation/input/{input.txt => input.rst}       | 238 +++---
 Documentation/input/interactive.fig                |  42 -
 Documentation/input/interactive.svg                |  24 +
 .../input/{joystick-api.txt => joystick-api.rst}   | 138 ++--
 Documentation/input/joystick-parport.rst           | 574 +++++++++++++
 Documentation/input/joystick-parport.txt           | 542 -------------
 Documentation/input/{joystick.txt => joystick.rst} | 541 +++++++------
 ...touch-protocol.txt => multi-touch-protocol.rst} | 196 +++--
 Documentation/input/{notifier.txt => notifier.rst} |  10 +-
 Documentation/input/{ntrig.txt => ntrig.rst}       |  49 +-
 .../{rotary-encoder.txt => rotary-encoder.rst}     |  74 +-
 Documentation/input/sentelic.rst                   | 901 +++++++++++++++++++++
 Documentation/input/sentelic.txt                   | 873 --------------------
 Documentation/input/shape.fig                      |  65 --
 Documentation/input/shape.svg                      |  39 +
 Documentation/input/{userio.txt => userio.rst}     |  79 +-
 .../input/{walkera0701.txt => walkera0701.rst}     |  53 +-
 Documentation/input/{xpad.txt => xpad.rst}         | 120 +--
 Documentation/input/{yealink.txt => yealink.rst}   | 164 ++--
 42 files changed, 4046 insertions(+), 3272 deletions(-)
 rename Documentation/input/{alps.txt => alps.rst} (95%)
 rename Documentation/input/{amijoy.txt => amijoy.rst} (63%)
 rename Documentation/input/{appletouch.txt => appletouch.rst} (81%)
 rename Documentation/input/{atarikbd.txt => atarikbd.rst} (91%)
 rename Documentation/input/{bcm5974.txt => bcm5974.rst} (55%)
 create mode 100644 Documentation/input/cd32.rst
 delete mode 100644 Documentation/input/cd32.txt
 rename Documentation/input/{cma3000_d0x.txt => cma3000_d0x.rst} (67%)
 create mode 100644 Documentation/input/conf.py
 rename Documentation/input/{cs461x.txt => cs461x.rst} (87%)
 rename Documentation/input/{edt-ft5x06.txt => edt-ft5x06.rst} (100%)
 rename Documentation/input/{elantech.txt => elantech.rst} (88%)
 rename Documentation/input/{event-codes.txt => event-codes.rst} (96%)
 rename Documentation/input/{ff.txt => ff.rst} (62%)
 rename Documentation/input/{gamepad.txt => gamepad.rst} (91%)
 rename Documentation/input/{gameport-programming.txt => gameport-programming.rst} (85%)
 create mode 100644 Documentation/input/gpio-tilt.rst
 delete mode 100644 Documentation/input/gpio-tilt.txt
 create mode 100644 Documentation/input/iforce-protocol.rst
 delete mode 100644 Documentation/input/iforce-protocol.txt
 create mode 100644 Documentation/input/index.rst
 rename Documentation/input/{input-programming.txt => input-programming.rst} (69%)
 rename Documentation/input/{input.txt => input.rst} (55%)
 delete mode 100644 Documentation/input/interactive.fig
 create mode 100644 Documentation/input/interactive.svg
 rename Documentation/input/{joystick-api.txt => joystick-api.rst} (79%)
 create mode 100644 Documentation/input/joystick-parport.rst
 delete mode 100644 Documentation/input/joystick-parport.txt
 rename Documentation/input/{joystick.txt => joystick.rst} (50%)
 rename Documentation/input/{multi-touch-protocol.txt => multi-touch-protocol.rst} (68%)
 rename Documentation/input/{notifier.txt => notifier.rst} (90%)
 rename Documentation/input/{ntrig.txt => ntrig.rst} (75%)
 rename Documentation/input/{rotary-encoder.txt => rotary-encoder.rst} (75%)
 create mode 100644 Documentation/input/sentelic.rst
 delete mode 100644 Documentation/input/sentelic.txt
 delete mode 100644 Documentation/input/shape.fig
 create mode 100644 Documentation/input/shape.svg
 rename Documentation/input/{userio.txt => userio.rst} (56%)
 rename Documentation/input/{walkera0701.txt => walkera0701.rst} (86%)
 rename Documentation/input/{xpad.txt => xpad.rst} (81%)
 rename Documentation/input/{yealink.txt => yealink.rst} (63%)

-- 
2.9.3

[PATCH v2 01/33] docs: Documentation/input/input: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST.

Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/input.txt | 240 +++++++++++++++++++++++-------------------
 1 file changed, 131 insertions(+), 109 deletions(-)

diff --git a/Documentation/input/input.txt b/Documentation/input/input.txt
index 7ebce100fe90..fda995e0ceb0 100644
--- a/Documentation/input/input.txt
+++ b/Documentation/input/input.txt
@@ -1,59 +1,67 @@
-			  Linux Input drivers v1.0
-	       (c) 1999-2001 Vojtech Pavlik <vojtech@ucw.cz>
-			     Sponsored by SuSE
-----------------------------------------------------------------------------
-
-0. Disclaimer
-~~~~~~~~~~~~~
-  This program is free software; you can redistribute it and/or modify it
+.. include:: <isonum.txt>
+
+===================
+Linux Input drivers
+===================
+
+:Copyright: |copy| 1999-2001 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
+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
+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
+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
+For your convenience, the GNU General Public License version 2 is included
 in the package: See the file COPYING.
 
-1. Introduction
-~~~~~~~~~~~~~~~
-  This is a collection of drivers that is designed to support all input
+Introduction
+============
+
+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/.
 
-  The centre of the input drivers is the input module, which must be
+The centre of the input drivers 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:
 
-1.1 Device drivers
-~~~~~~~~~~~~~~~~~~
-  These modules talk to the hardware (for example via USB), and provide
+Device drivers
+--------------
+
+These modules talk to the hardware (for example via USB), and provide
 events (keystrokes, mouse movements) to the input module.
 
-1.2 Event handlers
-~~~~~~~~~~~~~~~~~~
-  These modules get events from input and pass them where needed via
+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.
 
-2. Simple Usage
-~~~~~~~~~~~~~~~
-  For the most usual configuration, with one USB mouse and one USB keyboard,
+Simple Usage
+============
+
+For the most usual configuration, with one USB mouse and one USB keyboard,
 you'll have to load the following modules (or have them built in to the
-kernel):
+kernel)::
 
 	input
 	mousedev
@@ -62,24 +70,25 @@ kernel):
 	uhci_hcd or ohci_hcd or ehci_hcd
 	usbhid
 
-  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:
+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 has to be created.
+
+The commands to create it by hand are::
 
 	cd /dev
 	mkdir input
 	mknod input/mice c 13 63
 
-  After that you have to point GPM (the textmode mouse cut&paste tool) and
-XFree to this device to use it - GPM should be called like:
+After that you have to point GPM (the textmode mouse cut&paste tool) and
+XFree to this device to use it - GPM should be called like::
 
 	gpm -t ps2 -m /dev/input/mice
 
-  And in X:
+And in X::
 
 	Section "Pointer"
 	    Protocol    "ImPS/2"
@@ -87,97 +96,107 @@ XFree to this device to use it - GPM should be called like:
 	    ZAxisMapping 4 5
 	EndSection
 
-  When you do all of the above, you can use your USB mouse and keyboard.
+When you do all of the above, you can use your USB mouse and keyboard.
 
-3. Detailed Description
-~~~~~~~~~~~~~~~~~~~~~~~
-3.1 Device drivers
-~~~~~~~~~~~~~~~~~~
-  Device drivers are the modules that generate events. The events are
+Detailed Description
+====================
+
+Device drivers
+--------------
+
+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.
 
-3.1.1 usbhid
-~~~~~~~~~~~~
-  usbhid is the largest and most complex driver of the whole suite. It
+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
+Currently, it handles USB mice, joysticks, gamepads, steering wheels
 keyboards, trackballs and digitizers.
 
- However, USB uses HID also for monitor controls, speaker controls, UPSs,
+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
+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,
+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
+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.
 
-3.1.2 usbmouse
-~~~~~~~~~~~~~~
-  For embedded systems, for mice with broken HID descriptors and just any
+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.
 
-3.1.3 usbkbd
-~~~~~~~~~~~~
-  Much like usbmouse, this module talks to keyboards with a simplified
+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.
 
-3.1.4 wacom
-~~~~~~~~~~~
-  This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom
+wacom
+~~~~~
+
+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.
 
-3.1.5 iforce
-~~~~~~~~~~~~
-  A driver for I-Force joysticks and wheels, both over USB and RS232. 
+iforce
+~~~~~~
+
+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. 
+about it.
 
-3.2 Event handlers
-~~~~~~~~~~~~~~~~~~
-  Event handlers distribute the events from the devices to userland and
+Event handlers
+--------------
+
+Event handlers distribute the events from the devices to userland and
 kernel, as needed.
 
-3.2.1 keybdev
-~~~~~~~~~~~~~
-  keybdev is currently a rather ugly hack that translates the input
+keybdev
+~~~~~~~
+
+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.
 
-  The right way would be to pass the events to keyboard.c directly,
+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. 
+the input patch, available on the webpage mentioned below.
 
-3.2.2 mousedev
-~~~~~~~~~~~~~~
-  mousedev is also a hack to make programs that use mouse input
+mousedev
+~~~~~~~~
+
+mousedev is also a hack to make 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
 
-  Mousedev devices in /dev/input (as shown above) are:
+Mousedev devices in /dev/input (as shown above) are::
 
 	crw-r--r--   1 root     root      13,  32 Mar 28 22:45 mouse0
 	crw-r--r--   1 root     root      13,  33 Mar 29 00:41 mouse1
@@ -188,31 +207,32 @@ for example evdev
 	crw-r--r--   1 root     root      13,  62 Apr  1 10:50 mouse30
 	crw-r--r--   1 root     root      13,  63 Apr  1 10:50 mice
 
-Each 'mouse' device is assigned to a single mouse or digitizer, except
-the last one - 'mice'. This single character device is shared by all
+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.
 
-  CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
+CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
 the size of your screen (in pixels) in XFree86. This is needed if you
 want to use your digitizer in X, because its movement is sent to X
 via a virtual PS/2 mouse and thus needs to be scaled
 accordingly. These values won't be used if you use a mouse only.
 
-  Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
+Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
 ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the
 program reading the data wishes. You can set GPM and X to any of
 these. You'll need ImPS/2 if you want to make use of a wheel on a USB
-mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons. 
+mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons.
 
-3.2.3 joydev
-~~~~~~~~~~~~
-  Joydev implements v0.x and v1.x Linux joystick api, much like
+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: 
+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
@@ -222,19 +242,20 @@ on:
 
 And so on up to js31.
 
-3.2.4 evdev
-~~~~~~~~~~~
-  evdev is the generic input event interface. It passes the events
+evdev
+~~~~~
+
+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. 
+section 5.
 
-  This should be the way for GPM and X to get keyboard and mouse
+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.
 
-  The devices are in /dev/input:
+The devices are in /dev/input::
 
 	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
@@ -244,47 +265,48 @@ are hardware independent.
 
 And so on up to event31.
 
-4. Verifying if it works
-~~~~~~~~~~~~~~~~~~~~~~~~
-  Typing a couple keys on the keyboard should be enough to check that
+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
-driver. 
+driver.
 
-  Doing a "cat /dev/input/mouse0" (c, 13, 32) will verify that a mouse
+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,
+You can test the joystick emulation with the ``jstest`` utility,
 available in the joystick package (see Documentation/input/joystick.txt).
 
-  You can test the event devices with the 'evtest' utility available
+You can test the event devices with the ``evtest`` utility available
 in the LinuxConsole project CVS archive (see the URL below).
 
-5. Event interface
-~~~~~~~~~~~~~~~~~~
-  Should you want to add event device support into any application (X, gpm,
+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, 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:
+events on a read. Their layout is::
 
-struct input_event {
-	struct timeval time;
-	unsigned short type;
-	unsigned short code;
-	unsigned int value;
-};
+    struct input_event {
+	    struct timeval time;
+	    unsigned short type;
+	    unsigned short code;
+	    unsigned int value;
+    };
 
-  'time' is the timestamp, it returns the time at which the event happened.
+``time`` is the timestamp, it returns the time at which the event happened.
 Type is for example EV_REL for relative moment, EV_KEY for a keypress or
 release. More types are defined in include/uapi/linux/input-event-codes.h.
 
-  'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete
+``code`` is event code, for example REL_X or KEY_BACKSPACE, again a complete
 list is in include/uapi/linux/input-event-codes.h.
 
-  'value' is the value the event carries. Either a relative change for
+``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.
-
-- 
2.9.3

[PATCH v2 06/33] docs: input/bcm5974: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/bcm5974.txt | 43 +++++++++++++++++++++++------------------
 1 file changed, 24 insertions(+), 19 deletions(-)

diff --git a/Documentation/input/bcm5974.txt b/Documentation/input/bcm5974.txt
index 74d3876d6f34..4aca199b0aa6 100644
--- a/Documentation/input/bcm5974.txt
+++ b/Documentation/input/bcm5974.txt
@@ -1,19 +1,25 @@
+.. 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/
-- 
2.9.3

[PATCH v2 07/33] docs: input/cd32: convert it to ReST format

[Mauro Carvalho Chehab]

Currently, it misses a title, and the table is not valid for
ReST.

Adjust them, in order for it to be able to parse on Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/cd32.txt | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/Documentation/input/cd32.txt b/Documentation/input/cd32.txt
index a003d9b41eca..2bffe0f33e5e 100644
--- a/Documentation/input/cd32.txt
+++ b/Documentation/input/cd32.txt
@@ -1,3 +1,7 @@
+==========
+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
@@ -5,15 +9,15 @@ 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)
-
+===========    =============
+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)
+===========    =============
-- 
2.9.3

[PATCH v2 11/33] docs: input/event-codes: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
---
 Documentation/input/event-codes.txt | 132 +++++++++++++++++++++++++-----------
 1 file changed, 92 insertions(+), 40 deletions(-)

diff --git a/Documentation/input/event-codes.txt b/Documentation/input/event-codes.txt
index 36ea940e5bb9..92db50954169 100644
--- a/Documentation/input/event-codes.txt
+++ b/Documentation/input/event-codes.txt
@@ -1,3 +1,8 @@
+=================
+Input event codes
+=================
+
+
 The input protocol uses a map of types and codes to express input device values
 to userspace. This document describes the types and codes and how and when they
 may be used.
@@ -17,82 +22,102 @@ reports supported by a device are also provided by sysfs in
 class/input/event*/device/capabilities/, and the properties of a device are
 provided in class/input/event*/device/properties.
 
-Event types:
+Event types
 ===========
+
 Event types are groupings of codes under a logical input construct. Each
 type has a set of applicable codes to be used in generating events. See the
 Codes section for details on valid codes for each type.
 
 * EV_SYN:
+
   - Used as markers to separate events. Events may be separated in time or in
     space, such as with the multitouch protocol.
 
 * EV_KEY:
+
   - Used to describe state changes of keyboards, buttons, or other key-like
     devices.
 
 * EV_REL:
+
   - Used to describe relative axis value changes, e.g. moving the mouse 5 units
     to the left.
 
 * EV_ABS:
+
   - Used to describe absolute axis value changes, e.g. describing the
     coordinates of a touch on a touchscreen.
 
 * EV_MSC:
+
   - Used to describe miscellaneous input data that do not fit into other types.
 
 * EV_SW:
+
   - Used to describe binary state input switches.
 
 * EV_LED:
+
   - Used to turn LEDs on devices on and off.
 
 * EV_SND:
+
   - Used to output sound to devices.
 
 * EV_REP:
+
   - Used for autorepeating devices.
 
 * EV_FF:
+
   - Used to send force feedback commands to an input device.
 
 * EV_PWR:
+
   - A special type for power button and switch input.
 
 * EV_FF_STATUS:
+
   - Used to receive force feedback device status.
 
-Event codes:
+Event codes
 ===========
+
 Event codes define the precise type of event.
 
-EV_SYN:
-----------
+EV_SYN
+------
+
 EV_SYN event values are undefined. Their usage is defined only by when they are
 sent in the evdev event stream.
 
 * SYN_REPORT:
+
   - Used to synchronize and separate events into packets of input data changes
     occurring at the same moment in time. For example, motion of a mouse may set
     the REL_X and REL_Y values for one motion, then emit a SYN_REPORT. The next
     motion will emit more REL_X and REL_Y values and send another SYN_REPORT.
 
 * SYN_CONFIG:
+
   - TBD
 
 * SYN_MT_REPORT:
+
   - Used to synchronize and separate touch events. See the
     multi-touch-protocol.txt document for more information.
 
 * SYN_DROPPED:
+
   - Used to indicate buffer overrun in the evdev client's event queue.
     Client should ignore all events up to and including next SYN_REPORT
     event and query the device (using EVIOCG* ioctls) to obtain its
     current state.
 
-EV_KEY:
-----------
+EV_KEY
+------
+
 EV_KEY events take the form KEY_<name> or BTN_<name>. For example, KEY_A is used
 to represent the 'A' key on a keyboard. When a key is depressed, an event with
 the key's code is emitted with value 1. When the key is released, an event is
@@ -103,6 +128,7 @@ BTN_<name> is used for other types of momentary switch events.
 A few EV_KEY codes have special meanings:
 
 * BTN_TOOL_<name>:
+
   - These codes are used in conjunction with input trackpads, tablets, and
     touchscreens. These devices may be used with fingers, pens, or other tools.
     When an event occurs and a tool is used, the corresponding BTN_TOOL_<name>
@@ -112,6 +138,7 @@ A few EV_KEY codes have special meanings:
     code when events are generated.
 
 * BTN_TOUCH:
+
     BTN_TOUCH is used for touch contact. While an input tool is determined to be
     within meaningful physical contact, the value of this property must be set
     to 1. Meaningful physical contact may mean any contact, or it may mean
@@ -132,6 +159,7 @@ future, this distinction will be deprecated and the device properties ioctl
 EVIOCGPROP, defined in linux/input.h, will be used to convey the device type.
 
 * BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP, BTN_TOOL_TRIPLETAP, BTN_TOOL_QUADTAP:
+
   - These codes denote one, two, three, and four finger interaction on a
     trackpad or touchscreen. For example, if the user uses two fingers and moves
     them on the touchpad in an effort to scroll content on screen,
@@ -147,8 +175,9 @@ a value of 1 in the same synchronization frame. This usage is deprecated.
 Note: In multitouch drivers, the input_mt_report_finger_count() function should
 be used to emit these codes. Please see multi-touch-protocol.txt for details.
 
-EV_REL:
-----------
+EV_REL
+------
+
 EV_REL events describe relative changes in a property. For example, a mouse may
 move to the left by a certain number of units, but its absolute position in
 space is unknown. If the absolute position is known, EV_ABS codes should be used
@@ -157,17 +186,20 @@ instead of EV_REL codes.
 A few EV_REL codes have special meanings:
 
 * REL_WHEEL, REL_HWHEEL:
+
   - These codes are used for vertical and horizontal scroll wheels,
     respectively.
 
-EV_ABS:
-----------
+EV_ABS
+------
+
 EV_ABS events describe absolute changes in a property. For example, a touchpad
 may emit coordinates for a touch location.
 
 A few EV_ABS codes have special meanings:
 
 * ABS_DISTANCE:
+
   - Used to describe the distance of a tool from an interaction surface. This
     event should only be emitted while the tool is hovering, meaning in close
     proximity of the device and while the value of the BTN_TOUCH code is 0. If
@@ -179,11 +211,13 @@ A few EV_ABS codes have special meanings:
     hardware and is otherwise independent of ABS_DISTANCE and/or BTN_TOUCH.
 
 * ABS_MT_<name>:
+
   - Used to describe multitouch input events. Please see
     multi-touch-protocol.txt for details.
 
-EV_SW:
-----------
+EV_SW
+-----
+
 EV_SW events describe stateful binary switches. For example, the SW_LID code is
 used to denote when a laptop lid is closed.
 
@@ -195,14 +229,16 @@ Upon resume, if the switch state is the same as before suspend, then the input
 subsystem will filter out the duplicate switch state reports. The driver does
 not need to keep the state of the switch at any time.
 
-EV_MSC:
-----------
+EV_MSC
+------
+
 EV_MSC events are used for input and output events that do not fall under other
 categories.
 
 A few EV_MSC codes have special meaning:
 
 * MSC_TIMESTAMP:
+
   - Used to report the number of microseconds since the last reset. This event
     should be coded as an uint32 value, which is allowed to wrap around with
     no special consequence. It is assumed that the time difference between two
@@ -211,39 +247,46 @@ A few EV_MSC codes have special meaning:
     unknown.  If the device does not provide this information, the driver must
     not provide it to user space.
 
-EV_LED:
-----------
+EV_LED
+------
+
 EV_LED events are used for input and output to set and query the state of
 various LEDs on devices.
 
-EV_REP:
-----------
+EV_REP
+------
+
 EV_REP events are used for specifying autorepeating events.
 
-EV_SND:
-----------
+EV_SND
+------
+
 EV_SND events are used for sending sound commands to simple sound output
 devices.
 
-EV_FF:
-----------
+EV_FF
+-----
+
 EV_FF events are used to initialize a force feedback capable device and to cause
 such device to feedback.
 
-EV_PWR:
-----------
+EV_PWR
+------
+
 EV_PWR events are a special type of event used specifically for power
 management. Its usage is not well defined. To be addressed later.
 
-Device properties:
+Device properties
 =================
+
 Normally, userspace sets up an input device based on the data it emits,
 i.e., the event types. In the case of two devices emitting the same event
 types, additional information can be provided in the form of device
 properties.
 
-INPUT_PROP_DIRECT + INPUT_PROP_POINTER:
+INPUT_PROP_DIRECT + INPUT_PROP_POINTER
 --------------------------------------
+
 The INPUT_PROP_DIRECT property indicates that device coordinates should be
 directly mapped to screen coordinates (not taking into account trivial
 transformations, such as scaling, flipping and rotating). Non-direct input
@@ -260,8 +303,9 @@ If neither INPUT_PROP_DIRECT or INPUT_PROP_POINTER are set, the property is
 considered undefined and the device type should be deduced in the
 traditional way, using emitted event types.
 
-INPUT_PROP_BUTTONPAD:
+INPUT_PROP_BUTTONPAD
 --------------------
+
 For touchpads where the button is placed beneath the surface, such that
 pressing down on the pad causes a button click, this property should be
 set. Common in clickpad notebooks and macbooks from 2009 and onwards.
@@ -270,8 +314,9 @@ Originally, the buttonpad property was coded into the bcm5974 driver
 version field under the name integrated button. For backwards
 compatibility, both methods need to be checked in userspace.
 
-INPUT_PROP_SEMI_MT:
+INPUT_PROP_SEMI_MT
 ------------------
+
 Some touchpads, most common between 2008 and 2011, can detect the presence
 of multiple contacts without resolving the individual positions; only the
 number of contacts and a rectangular shape is known. For such
@@ -285,9 +330,10 @@ gestures can normally be extracted from it.
 If INPUT_PROP_SEMI_MT is not set, the device is assumed to be a true MT
 device.
 
-INPUT_PROP_TOPBUTTONPAD:
+INPUT_PROP_TOPBUTTONPAD
 -----------------------
-Some laptops, most notably the Lenovo *40 series provide a trackstick
+
+Some laptops, most notably the Lenovo 40 series provide a trackstick
 device but do not have physical buttons associated with the trackstick
 device. Instead, the top area of the touchpad is marked to show
 visual/haptic areas for left, middle, right buttons intended to be used
@@ -299,26 +345,30 @@ The kernel does not provide button emulation for such devices but treats
 them as any other INPUT_PROP_BUTTONPAD device.
 
 INPUT_PROP_ACCELEROMETER
--------------------------
+------------------------
+
 Directional axes on this device (absolute and/or relative x, y, z) represent
 accelerometer data. All other axes retain their meaning. A device must not mix
 regular directional axes and accelerometer axes on the same event node.
 
-Guidelines:
+Guidelines
 ==========
+
 The guidelines below ensure proper single-touch and multi-finger functionality.
 For multi-touch functionality, see the multi-touch-protocol.txt document for
 more information.
 
-Mice:
-----------
+Mice
+----
+
 REL_{X,Y} must be reported when the mouse moves. BTN_LEFT must be used to report
 the primary button press. BTN_{MIDDLE,RIGHT,4,5,etc.} should be used to report
 further buttons of the device. REL_WHEEL and REL_HWHEEL should be used to report
 scroll wheel events where available.
 
-Touchscreens:
-----------
+Touchscreens
+------------
+
 ABS_{X,Y} must be reported with the location of the touch. BTN_TOUCH must be
 used to report when a touch is active on the screen.
 BTN_{MOUSE,LEFT,MIDDLE,RIGHT} must not be reported as the result of touch
@@ -326,8 +376,9 @@ contact. BTN_TOOL_<name> events should be reported where possible.
 
 For new hardware, INPUT_PROP_DIRECT should be set.
 
-Trackpads:
-----------
+Trackpads
+---------
+
 Legacy trackpads that only provide relative position information must report
 events like mice described above.
 
@@ -338,8 +389,9 @@ be used to report the number of touches active on the trackpad.
 
 For new hardware, INPUT_PROP_POINTER should be set.
 
-Tablets:
-----------
+Tablets
+-------
+
 BTN_TOOL_<name> events must be reported when a stylus or other tool is active on
 the tablet. ABS_{X,Y} must be reported with the location of the tool. BTN_TOUCH
 should be used to report when the tool is in contact with the tablet.
-- 
2.9.3

[PATCH v2 12/33] docs: input/ff: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/ff.txt | 188 +++++++++++++++++++++++++++------------------
 1 file changed, 112 insertions(+), 76 deletions(-)

diff --git a/Documentation/input/ff.txt b/Documentation/input/ff.txt
index b3867bf49f8f..6d6688a63dd8 100644
--- a/Documentation/input/ff.txt
+++ b/Documentation/input/ff.txt
@@ -1,12 +1,16 @@
-Force feedback for Linux.
-By Johann Deneux <johann.deneux@gmail.com> on 2001/04/22.
-Updated by Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09.
+========================
+Force feedback for Linux
+========================
+
+:Author: Johann Deneux <johann.deneux@gmail.com> on 2001/04/22.
+:Updated: Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09.
+
 You may redistribute this file. Please remember to include shape.fig and
 interactive.fig as well.
-----------------------------------------------------------------------------
 
-1. Introduction
-~~~~~~~~~~~~~~~
+Introduction
+~~~~~~~~~~~~
+
 This document describes how to use force feedback devices under Linux. The
 goal is not to support these devices as if they were simple input-only devices
 (as it is already the case), but to really enable the rendering of force
@@ -15,8 +19,9 @@ This document only describes the force feedback part of the Linux input
 interface. Please read joystick.txt and input.txt before reading further this
 document.
 
-2. Instructions to the user
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Instructions to the user
+~~~~~~~~~~~~~~~~~~~~~~~~
+
 To enable force feedback, you have to:
 
 1. have your kernel configured with evdev and a driver that supports your
@@ -33,39 +38,48 @@ something goes wrong.
 If you have a serial iforce device, you need to start inputattach. See
 joystick.txt for details.
 
-2.1 Does it work ?
-~~~~~~~~~~~~~~~~~~
-There is an utility called fftest that will allow you to test the driver.
-% fftest /dev/input/eventXX
+Does it work ?
+--------------
+
+There is an utility called fftest that will allow you to test the driver::
+
+    % fftest /dev/input/eventXX
+
+Instructions to the developer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-3. Instructions to the developer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 All interactions are done using the event API. That is, you can use ioctl()
 and write() on /dev/input/eventXX.
 This information is subject to change.
 
-3.1 Querying device capabilities
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#include <linux/input.h>
-#include <sys/ioctl.h>
+Querying device capabilities
+----------------------------
 
-#define BITS_TO_LONGS(x) \
-	(((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long)))
-unsigned long features[BITS_TO_LONGS(FF_CNT)];
-int ioctl(int file_descriptor, int request, unsigned long *features);
+::
+
+    #include <linux/input.h>
+    #include <sys/ioctl.h>
+
+    #define BITS_TO_LONGS(x) \
+	    (((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long)))
+    unsigned long features[BITS_TO_LONGS(FF_CNT)];
+    int ioctl(int file_descriptor, int request, unsigned long *features);
 
 "request" must be EVIOCGBIT(EV_FF, size of features array in bytes )
 
 Returns the features supported by the device. features is a bitfield with the
 following bits:
+
 - FF_CONSTANT	can render constant force effects
 - FF_PERIODIC	can render periodic effects with the following waveforms:
+
   - FF_SQUARE	  square waveform
   - FF_TRIANGLE	  triangle waveform
   - FF_SINE	  sine waveform
   - FF_SAW_UP	  sawtooth up waveform
   - FF_SAW_DOWN	  sawtooth down waveform
   - FF_CUSTOM	  custom waveform
+
 - FF_RAMP       can render ramp effects
 - FF_SPRING	can simulate the presence of a spring
 - FF_FRICTION	can simulate friction
@@ -75,24 +89,30 @@ following bits:
 - FF_GAIN	gain is adjustable
 - FF_AUTOCENTER	autocenter is adjustable
 
-Note: In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All
+.. note::
+
+    - In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All
       devices that support FF_RUMBLE support FF_PERIODIC (square, triangle,
       sine) and the other way around.
 
-Note: The exact syntax FF_CUSTOM is undefined for the time being as no driver
+    - The exact syntax FF_CUSTOM is undefined for the time being as no driver
       supports it yet.
 
+::
 
-int ioctl(int fd, EVIOCGEFFECTS, int *n);
+    int ioctl(int fd, EVIOCGEFFECTS, int *n);
 
 Returns the number of effects the device can keep in its memory.
 
-3.2 Uploading effects to the device
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#include <linux/input.h>
-#include <sys/ioctl.h>
+Uploading effects to the device
+-------------------------------
 
-int ioctl(int file_descriptor, int request, struct ff_effect *effect);
+::
+
+    #include <linux/input.h>
+    #include <sys/ioctl.h>
+
+    int ioctl(int file_descriptor, int request, struct ff_effect *effect);
 
 "request" must be EVIOCSFF.
 
@@ -110,34 +130,41 @@ See <linux/input.h> for a description of the ff_effect struct. You should also
 find help in a few sketches, contained in files shape.fig and interactive.fig.
 You need xfig to visualize these files.
 
-3.3 Removing an effect from the device
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-int ioctl(int fd, EVIOCRMFF, effect.id);
+
+Removing an effect from the device
+----------------------------------
+
+::
+
+    int ioctl(int fd, EVIOCRMFF, effect.id);
 
 This makes room for new effects in the device's memory. Note that this also
 stops the effect if it was playing.
 
-3.4 Controlling the playback of effects
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Controlling the playback of effects
+-----------------------------------
+
 Control of playing is done with write(). Below is an example:
 
-#include <linux/input.h>
-#include <unistd.h>
+::
+
+    #include <linux/input.h>
+    #include <unistd.h>
 
 	struct input_event play;
 	struct input_event stop;
 	struct ff_effect effect;
 	int fd;
-...
+   ...
 	fd = open("/dev/input/eventXX", O_RDWR);
-...
+   ...
 	/* Play three times */
 	play.type = EV_FF;
 	play.code = effect.id;
 	play.value = 3;
 
 	write(fd, (const void*) &play, sizeof(play));
-...
+   ...
 	/* Stop an effect */
 	stop.type = EV_FF;
 	stop.code = effect.id;
@@ -145,43 +172,50 @@ Control of playing is done with write(). Below is an example:
 
 	write(fd, (const void*) &play, sizeof(stop));
 
-3.5 Setting the gain
-~~~~~~~~~~~~~~~~~~~~
+Setting the gain
+----------------
+
 Not all devices have the same strength. Therefore, users should set a gain
 factor depending on how strong they want effects to be. This setting is
 persistent across access to the driver.
 
-/* Set the gain of the device
-int gain;		/* between 0 and 100 */
-struct input_event ie;	/* structure used to communicate with the driver */
+::
 
-ie.type = EV_FF;
-ie.code = FF_GAIN;
-ie.value = 0xFFFFUL * gain / 100;
+    /* Set the gain of the device
+    int gain;		/* between 0 and 100 */
+    struct input_event ie;	/* structure used to communicate with the driver */
 
-if (write(fd, &ie, sizeof(ie)) == -1)
+    ie.type = EV_FF;
+    ie.code = FF_GAIN;
+    ie.value = 0xFFFFUL * gain / 100;
+
+    if (write(fd, &ie, sizeof(ie)) == -1)
 	perror("set gain");
 
-3.6 Enabling/Disabling autocenter
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Enabling/Disabling autocenter
+-----------------------------
+
 The autocenter feature quite disturbs the rendering of effects in my opinion,
 and I think it should be an effect, which computation depends on the game
 type. But you can enable it if you want.
 
-int autocenter;		/* between 0 and 100 */
-struct input_event ie;
+::
 
-ie.type = EV_FF;
-ie.code = FF_AUTOCENTER;
-ie.value = 0xFFFFUL * autocenter / 100;
+    int autocenter;		/* between 0 and 100 */
+    struct input_event ie;
 
-if (write(fd, &ie, sizeof(ie)) == -1)
+    ie.type = EV_FF;
+    ie.code = FF_AUTOCENTER;
+    ie.value = 0xFFFFUL * autocenter / 100;
+
+    if (write(fd, &ie, sizeof(ie)) == -1)
 	perror("set auto-center");
 
 A value of 0 means "no auto-center".
 
-3.7 Dynamic update of an effect
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Dynamic update of an effect
+---------------------------
+
 Proceed as if you wanted to upload a new effect, except that instead of
 setting the id field to -1, you set it to the wanted effect id.
 Normally, the effect is not stopped and restarted. However, depending on the
@@ -192,30 +226,32 @@ case, the driver stops the effect, up-load it, and restart it.
 Therefore it is recommended to dynamically change direction while the effect
 is playing only when it is ok to restart the effect with a replay count of 1.
 
-3.8 Information about the status of effects
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Information about the status of effects
+---------------------------------------
+
 Every time the status of an effect is changed, an event is sent. The values
-and meanings of the fields of the event are as follows:
+and meanings of the fields of the event are as follows::
 
-struct input_event {
-/* When the status of the effect changed */
-	struct timeval time;
+    struct input_event {
+    /* When the status of the effect changed */
+	    struct timeval time;
 
-/* Set to EV_FF_STATUS */
-	unsigned short type;
+    /* Set to EV_FF_STATUS */
+	    unsigned short type;
 
-/* Contains the id of the effect */
-	unsigned short code;
+    /* Contains the id of the effect */
+	    unsigned short code;
 
-/* Indicates the status */
-	unsigned int value;
-};
+    /* Indicates the status */
+	    unsigned int value;
+    };
 
-FF_STATUS_STOPPED	The effect stopped playing
-FF_STATUS_PLAYING	The effect started to play
+    FF_STATUS_STOPPED	The effect stopped playing
+    FF_STATUS_PLAYING	The effect started to play
 
-NOTE: Status feedback is only supported by iforce driver. If you have
+.. note::
+
+    - Status feedback is only supported by iforce driver. If you have
       a really good reason to use this, please contact
       linux-joystick@atrey.karlin.mff.cuni.cz or anssi.hannula@gmail.com
       so that support for it can be added to the rest of the drivers.
-
-- 
2.9.3

[PATCH v2 15/33] docs: input/gpio-tilt: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/gpio-tilt.txt | 124 +++++++++++++++++++-------------------
 1 file changed, 62 insertions(+), 62 deletions(-)

diff --git a/Documentation/input/gpio-tilt.txt b/Documentation/input/gpio-tilt.txt
index 2cdfd9bcb1af..23de9eff6a34 100644
--- a/Documentation/input/gpio-tilt.txt
+++ b/Documentation/input/gpio-tilt.txt
@@ -28,76 +28,76 @@ 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) {
-	/* code to enable the sensors */
-};
+    static int sg060_tilt_enable(struct device *dev) {
+	    /* code to enable the sensors */
+    };
 
-static void sg060_tilt_disable(struct device *dev) {
-	/* code to disable the sensors */
-};
+    static void sg060_tilt_disable(struct device *dev) {
+	    /* code to disable the sensors */
+    };
 
-static struct gpio sg060_tilt_gpios[] = {
-	{ SG060_TILT_GPIO_SENSOR1, GPIOF_IN, "tilt_sensor1" },
-	{ SG060_TILT_GPIO_SENSOR2, GPIOF_IN, "tilt_sensor2" },
-};
+    static struct gpio sg060_tilt_gpios[] = {
+	    { SG060_TILT_GPIO_SENSOR1, GPIOF_IN, "tilt_sensor1" },
+	    { SG060_TILT_GPIO_SENSOR2, GPIOF_IN, "tilt_sensor2" },
+    };
 
-static struct gpio_tilt_state sg060_tilt_states[] = {
-	{
-		.gpios = (0 << 1) | (0 << 0),
-		.axes = (int[]) {
-			0,
-		},
-	}, {
-		.gpios = (0 << 1) | (1 << 0),
-		.axes = (int[]) {
-			1, /* 90 degrees */
-		},
-	}, {
-		.gpios = (1 << 1) | (1 << 0),
-		.axes = (int[]) {
-			2, /* 180 degrees */
-		},
-	}, {
-		.gpios = (1 << 1) | (0 << 0),
-		.axes = (int[]) {
-			3, /* 270 degrees */
-		},
-	},
-};
+    static struct gpio_tilt_state sg060_tilt_states[] = {
+	    {
+		    .gpios = (0 << 1) | (0 << 0),
+		    .axes = (int[]) {
+			    0,
+		    },
+	    }, {
+		    .gpios = (0 << 1) | (1 << 0),
+		    .axes = (int[]) {
+			    1, /* 90 degrees */
+		    },
+	    }, {
+		    .gpios = (1 << 1) | (1 << 0),
+		    .axes = (int[]) {
+			    2, /* 180 degrees */
+		    },
+	    }, {
+		    .gpios = (1 << 1) | (0 << 0),
+		    .axes = (int[]) {
+			    3, /* 270 degrees */
+		    },
+	    },
+    };
 
-static struct gpio_tilt_axis sg060_tilt_axes[] = {
-	{
-		.axis = ABS_RY,
-		.min = 0,
-		.max = 3,
-		.fuzz = 0,
-		.flat = 0,
-	},
-};
+    static struct gpio_tilt_axis sg060_tilt_axes[] = {
+	    {
+		    .axis = ABS_RY,
+		    .min = 0,
+		    .max = 3,
+		    .fuzz = 0,
+		    .flat = 0,
+	    },
+    };
 
-static struct gpio_tilt_platform_data sg060_tilt_pdata= {
-	.gpios = sg060_tilt_gpios,
-	.nr_gpios = ARRAY_SIZE(sg060_tilt_gpios),
+    static struct gpio_tilt_platform_data sg060_tilt_pdata= {
+	    .gpios = sg060_tilt_gpios,
+	    .nr_gpios = ARRAY_SIZE(sg060_tilt_gpios),
 
-	.axes = sg060_tilt_axes,
-	.nr_axes = ARRAY_SIZE(sg060_tilt_axes),
+	    .axes = sg060_tilt_axes,
+	    .nr_axes = ARRAY_SIZE(sg060_tilt_axes),
 
-	.states = sg060_tilt_states,
-	.nr_states = ARRAY_SIZE(sg060_tilt_states),
+	    .states = sg060_tilt_states,
+	    .nr_states = ARRAY_SIZE(sg060_tilt_states),
 
-	.debounce_interval = 100,
+	    .debounce_interval = 100,
 
-	.poll_interval = 1000,
-	.enable = sg060_tilt_enable,
-	.disable = sg060_tilt_disable,
-};
+	    .poll_interval = 1000,
+	    .enable = sg060_tilt_enable,
+	    .disable = sg060_tilt_disable,
+    };
 
-static struct platform_device sg060_device_tilt = {
-	.name = "gpio-tilt-polled",
-	.id = -1,
-	.dev = {
-		.platform_data = &sg060_tilt_pdata,
-	},
-};
+    static struct platform_device sg060_device_tilt = {
+	    .name = "gpio-tilt-polled",
+	    .id = -1,
+	    .dev = {
+		    .platform_data = &sg060_tilt_pdata,
+	    },
+    };
-- 
2.9.3

[PATCH v2 17/33] docs: input/input-programming: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/input-programming.txt | 253 +++++++++++++++---------------
 1 file changed, 128 insertions(+), 125 deletions(-)

diff --git a/Documentation/input/input-programming.txt b/Documentation/input/input-programming.txt
index 7f8b9d97bc47..4d3b22222e93 100644
--- a/Documentation/input/input-programming.txt
+++ b/Documentation/input/input-programming.txt
@@ -1,77 +1,78 @@
+~~~~~~~~~~~~~~~~~~~~~~~~~
 Programming input drivers
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-1. Creating an input device driver
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Creating an input device driver
+===============================
 
-1.0 The simplest example
-~~~~~~~~~~~~~~~~~~~~~~~~
+The simplest example
+~~~~~~~~~~~~~~~~~~~~
 
 Here comes a very simple example of an input device driver. The device has
 just one button and the button is accessible at i/o port BUTTON_PORT. When
-pressed or released a BUTTON_IRQ happens. The driver could look like:
-
-#include <linux/input.h>
-#include <linux/module.h>
-#include <linux/init.h>
-
-#include <asm/irq.h>
-#include <asm/io.h>
-
-static struct input_dev *button_dev;
-
-static irqreturn_t button_interrupt(int irq, void *dummy)
-{
-	input_report_key(button_dev, BTN_0, inb(BUTTON_PORT) & 1);
-	input_sync(button_dev);
-	return IRQ_HANDLED;
-}
-
-static int __init button_init(void)
-{
-	int error;
-
-	if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) {
-                printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq);
-                return -EBUSY;
-        }
-
-	button_dev = input_allocate_device();
-	if (!button_dev) {
-		printk(KERN_ERR "button.c: Not enough memory\n");
-		error = -ENOMEM;
-		goto err_free_irq;
-	}
-
-	button_dev->evbit[0] = BIT_MASK(EV_KEY);
-	button_dev->keybit[BIT_WORD(BTN_0)] = BIT_MASK(BTN_0);
-
-	error = input_register_device(button_dev);
-	if (error) {
-		printk(KERN_ERR "button.c: Failed to register device\n");
-		goto err_free_dev;
-	}
-
-	return 0;
-
- err_free_dev:
-	input_free_device(button_dev);
- err_free_irq:
-	free_irq(BUTTON_IRQ, button_interrupt);
-	return error;
-}
-
-static void __exit button_exit(void)
-{
-        input_unregister_device(button_dev);
-	free_irq(BUTTON_IRQ, button_interrupt);
-}
-
-module_init(button_init);
-module_exit(button_exit);
-
-1.1 What the example does
-~~~~~~~~~~~~~~~~~~~~~~~~~
+pressed or released a BUTTON_IRQ happens. The driver could look like::
+
+    #include <linux/input.h>
+    #include <linux/module.h>
+    #include <linux/init.h>
+
+    #include <asm/irq.h>
+    #include <asm/io.h>
+
+    static struct input_dev *button_dev;
+
+    static irqreturn_t button_interrupt(int irq, void *dummy)
+    {
+	    input_report_key(button_dev, BTN_0, inb(BUTTON_PORT) & 1);
+	    input_sync(button_dev);
+	    return IRQ_HANDLED;
+    }
+
+    static int __init button_init(void)
+    {
+	    int error;
+
+	    if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) {
+		    printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq);
+		    return -EBUSY;
+	    }
+
+	    button_dev = input_allocate_device();
+	    if (!button_dev) {
+		    printk(KERN_ERR "button.c: Not enough memory\n");
+		    error = -ENOMEM;
+		    goto err_free_irq;
+	    }
+
+	    button_dev->evbit[0] = BIT_MASK(EV_KEY);
+	    button_dev->keybit[BIT_WORD(BTN_0)] = BIT_MASK(BTN_0);
+
+	    error = input_register_device(button_dev);
+	    if (error) {
+		    printk(KERN_ERR "button.c: Failed to register device\n");
+		    goto err_free_dev;
+	    }
+
+	    return 0;
+
+    err_free_dev:
+	    input_free_device(button_dev);
+    err_free_irq:
+	    free_irq(BUTTON_IRQ, button_interrupt);
+	    return error;
+    }
+
+    static void __exit button_exit(void)
+    {
+	    input_unregister_device(button_dev);
+	    free_irq(BUTTON_IRQ, button_interrupt);
+    }
+
+    module_init(button_init);
+    module_exit(button_exit);
+
+What the example does
+~~~~~~~~~~~~~~~~~~~~~
 
 First it has to include the <linux/input.h> file, which interfaces to the
 input subsystem. This provides all the definitions needed.
@@ -85,7 +86,7 @@ and sets up input bitfields. This way the device driver tells the other
 parts of the input systems what it is - what events can be generated or
 accepted by this input device. Our example device can only generate EV_KEY
 type events, and from those only BTN_0 event code. Thus we only set these
-two bits. We could have used
+two bits. We could have used::
 
 	set_bit(EV_KEY, button_dev.evbit);
 	set_bit(BTN_0, button_dev.keybit);
@@ -93,7 +94,7 @@ two bits. We could have used
 as well, but with more than single bits the first approach tends to be
 shorter.
 
-Then the example driver registers the input device structure by calling
+Then the example driver registers the input device structure by calling::
 
 	input_register_device(&button_dev);
 
@@ -102,12 +103,12 @@ calls device handler modules _connect functions to tell them a new input
 device has appeared. input_register_device() may sleep and therefore must
 not be called from an interrupt or with a spinlock held.
 
-While in use, the only used function of the driver is
+While in use, the only used function of the driver is::
 
 	button_interrupt()
 
 which upon every interrupt from the button checks its state and reports it
-via the
+via the::
 
 	input_report_key()
 
@@ -116,7 +117,7 @@ routine isn't reporting two same value events (press, press for example) to
 the input system, because the input_report_* functions check that
 themselves.
 
-Then there is the
+Then there is the::
 
 	input_sync()
 
@@ -125,38 +126,38 @@ This doesn't seem important in the one button case, but is quite important
 for for example mouse movement, where you don't want the X and Y values
 to be interpreted separately, because that'd result in a different movement.
 
-1.2 dev->open() and dev->close()
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+dev->open() and dev->close()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In case the driver has to repeatedly poll the device, because it doesn't
 have an interrupt coming from it and the polling is too expensive to be done
 all the time, or if the device uses a valuable resource (eg. interrupt), it
 can use the open and close callback to know when it can stop polling or
 release the interrupt and when it must resume polling or grab the interrupt
-again. To do that, we would add this to our example driver:
+again. To do that, we would add this to our example driver::
 
-static int button_open(struct input_dev *dev)
-{
-	if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) {
-                printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq);
-                return -EBUSY;
-        }
+    static int button_open(struct input_dev *dev)
+    {
+	    if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) {
+		    printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq);
+		    return -EBUSY;
+	    }
 
-        return 0;
-}
+	    return 0;
+    }
 
-static void button_close(struct input_dev *dev)
-{
-        free_irq(IRQ_AMIGA_VERTB, button_interrupt);
-}
+    static void button_close(struct input_dev *dev)
+    {
+	    free_irq(IRQ_AMIGA_VERTB, button_interrupt);
+    }
 
-static int __init button_init(void)
-{
-	...
-	button_dev->open = button_open;
-	button_dev->close = button_close;
-	...
-}
+    static int __init button_init(void)
+    {
+	    ...
+	    button_dev->open = button_open;
+	    button_dev->close = button_close;
+	    ...
+    }
 
 Note that input core keeps track of number of users for the device and
 makes sure that dev->open() is called only when the first user connects
@@ -166,11 +167,11 @@ disconnects. Calls to both callbacks are serialized.
 The open() callback should return a 0 in case of success or any nonzero value
 in case of failure. The close() callback (which is void) must always succeed.
 
-1.3 Basic event types
-~~~~~~~~~~~~~~~~~~~~~
+Basic event types
+~~~~~~~~~~~~~~~~~
 
 The most simple event type is EV_KEY, which is used for keys and buttons.
-It's reported to the input system via:
+It's reported to the input system via::
 
 	input_report_key(struct input_dev *dev, int code, int value)
 
@@ -188,7 +189,7 @@ events are namely for joysticks and digitizers - devices that do work in an
 absolute coordinate systems.
 
 Having the device report EV_REL buttons is as simple as with EV_KEY, simply
-set the corresponding bits and call the
+set the corresponding bits and call the::
 
 	input_report_rel(struct input_dev *dev, int code, int value)
 
@@ -197,14 +198,14 @@ function. Events are generated only for nonzero value.
 However EV_ABS requires a little special care. Before calling
 input_register_device, you have to fill additional fields in the input_dev
 struct for each absolute axis your device has. If our button device had also
-the ABS_X axis:
+the ABS_X axis::
 
 	button_dev.absmin[ABS_X] = 0;
 	button_dev.absmax[ABS_X] = 255;
 	button_dev.absfuzz[ABS_X] = 4;
 	button_dev.absflat[ABS_X] = 8;
 
-Or, you can just say:
+Or, you can just say::
 
 	input_set_abs_params(button_dev, ABS_X, 0, 255, 4, 8);
 
@@ -218,18 +219,18 @@ If you don't need absfuzz and absflat, you can set them to zero, which mean
 that the thing is precise and always returns to exactly the center position
 (if it has any).
 
-1.4 BITS_TO_LONGS(), BIT_WORD(), BIT_MASK()
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+BITS_TO_LONGS(), BIT_WORD(), BIT_MASK()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These three macros from bitops.h help some bitfield computations:
+These three macros from bitops.h help some bitfield computations::
 
 	BITS_TO_LONGS(x) - returns the length of a bitfield array in longs for
 			   x bits
 	BIT_WORD(x)	 - returns the index in the array in longs for bit x
 	BIT_MASK(x)	 - returns the index in a long for bit x
 
-1.5 The id* and name fields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The id* and name fields
+~~~~~~~~~~~~~~~~~~~~~~~
 
 The dev->name should be set before registering the input device by the input
 device driver. It's a string like 'Generic button device' containing a
@@ -245,8 +246,8 @@ driver.
 
 The id and name fields can be passed to userland via the evdev interface.
 
-1.6 The keycode, keycodemax, keycodesize fields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The keycode, keycodemax, keycodesize fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These three fields should be used by input devices that have dense keymaps.
 The keycode is an array used to map from scancodes to input system keycodes.
@@ -259,14 +260,15 @@ When a device has all 3 aforementioned fields filled in, the driver may
 rely on kernel's default implementation of setting and querying keycode
 mappings.
 
-1.7 dev->getkeycode() and dev->setkeycode()
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+dev->getkeycode() and dev->setkeycode()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 getkeycode() and setkeycode() callbacks allow drivers to override default
 keycode/keycodesize/keycodemax mapping mechanism provided by input core
 and implement sparse keycode maps.
 
-1.8 Key autorepeat
-~~~~~~~~~~~~~~~~~~
+Key autorepeat
+~~~~~~~~~~~~~~
 
 ... is simple. It is handled by the input.c module. Hardware autorepeat is
 not used, because it's not present in many devices and even where it is
@@ -274,29 +276,30 @@ present, it is broken sometimes (at keyboards: Toshiba notebooks). To enable
 autorepeat for your device, just set EV_REP in dev->evbit. All will be
 handled by the input system.
 
-1.9 Other event types, handling output events
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Other event types, handling output events
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The other event types up to now are:
 
-EV_LED - used for the keyboard LEDs.
-EV_SND - used for keyboard beeps.
+- EV_LED - used for the keyboard LEDs.
+- EV_SND - used for keyboard beeps.
 
 They are very similar to for example key events, but they go in the other
 direction - from the system to the input device driver. If your input device
 driver can handle these events, it has to set the respective bits in evbit,
-*and* also the callback routine:
+*and* also the callback routine::
 
-	button_dev->event = button_event;
+    button_dev->event = button_event;
 
-int button_event(struct input_dev *dev, unsigned int type, unsigned int code, int value);
-{
-	if (type == EV_SND && code == SND_BELL) {
-		outb(value, BUTTON_BELL);
-		return 0;
-	}
-	return -1;
-}
+    int button_event(struct input_dev *dev, unsigned int type,
+		     unsigned int code, int value)
+    {
+	    if (type == EV_SND && code == SND_BELL) {
+		    outb(value, BUTTON_BELL);
+		    return 0;
+	    }
+	    return -1;
+    }
 
 This callback routine can be called from an interrupt or a BH (although that
 isn't a rule), and thus must not sleep, and must not take too long to finish.
-- 
2.9.3

[PATCH v2 19/33] docs: input/joystick: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/joystick.txt | 541 +++++++++++++++++++++------------------
 1 file changed, 293 insertions(+), 248 deletions(-)

diff --git a/Documentation/input/joystick.txt b/Documentation/input/joystick.txt
index 8d027dc86c1f..202f5a090675 100644
--- a/Documentation/input/joystick.txt
+++ b/Documentation/input/joystick.txt
@@ -1,271 +1,291 @@
-		       Linux Joystick driver v2.0.0
-	       (c) 1996-2000 Vojtech Pavlik <vojtech@ucw.cz>
-			     Sponsored by SuSE
-----------------------------------------------------------------------------
-
-0. Disclaimer
-~~~~~~~~~~~~~
-  This program is free software; you can redistribute it and/or modify it
+.. 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
+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
+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
+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
+For your convenience, the GNU General Public License version 2 is included
 in the package: See the file COPYING.
 
-1. Intro
-~~~~~~~~
-  The joystick driver for Linux provides support for a variety of joysticks
+Intro
+=====
+
+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
+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:
+The input project website is at:
 
 	http://atrey.karlin.mff.cuni.cz/~vojtech/input/
 
-  There is also a mailing list for the driver at:
+There is also a mailing list for the driver at:
 
 	listproc@atrey.karlin.mff.cuni.cz
 
 send "subscribe linux-joystick Your Name" to subscribe to it.
 
-2. Usage
-~~~~~~~~
-  For basic usage you just choose the right options in kernel config and
+Usage
+=====
+
+For basic usage you just choose the right options in kernel config and
 you should be set.
 
-2.1 inpututils
-~~~~~~~~~~~~~~
+inpututils
+----------
+
 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.
 
-2.2 Device nodes
-~~~~~~~~~~~~~~~~
+Device nodes
+------------
+
 For applications to be able to use the joysticks,
-you'll have to manually create these nodes in /dev:
+you'll have to manually create these nodes in /dev::
 
-cd /dev
-rm js*
-mkdir input
-mknod input/js0 c 13 0
-mknod input/js1 c 13 1
-mknod input/js2 c 13 2
-mknod input/js3 c 13 3
-ln -s input/js0 js0
-ln -s input/js1 js1
-ln -s input/js2 js2
-ln -s input/js3 js3
+    cd /dev
+    rm js*
+    mkdir input
+    mknod input/js0 c 13 0
+    mknod input/js1 c 13 1
+    mknod input/js2 c 13 2
+    mknod input/js3 c 13 3
+    ln -s input/js0 js0
+    ln -s input/js1 js1
+    ln -s input/js2 js2
+    ln -s input/js3 js3
 
-For testing with inpututils it's also convenient to create these:
+For testing with inpututils it's also convenient to create these::
 
-mknod input/event0 c 13 64
-mknod input/event1 c 13 65
-mknod input/event2 c 13 66
-mknod input/event3 c 13 67
+    mknod input/event0 c 13 64
+    mknod input/event1 c 13 65
+    mknod input/event2 c 13 66
+    mknod input/event3 c 13 67
 
-2.4 Modules needed 
-~~~~~~~~~~~~~~~~~~
-  For all joystick drivers to function, you'll need the userland interface
-module in kernel, either loaded or compiled in:
+Modules needed
+--------------
+
+For all joystick drivers to function, you'll need the userland interface
+module in kernel, either loaded or compiled in::
 
 	modprobe joydev
 
-  For gameport joysticks, you'll have to load the gameport driver as well;
+For gameport joysticks, you'll have to load the gameport driver as well::
 
 	modprobe ns558
 
-  And for serial port joysticks, you'll need the serial input line
-discipline module loaded and the inputattach utility started:
+And for serial port joysticks, you'll need the serial input line
+discipline module loaded and the inputattach utility started::
 
 	modprobe serport
 	inputattach -xxx /dev/tts/X &
 
-  In addition to that, you'll need the joystick driver module itself, most
-usually you'll have an analog joystick:
+In addition to that, you'll need the joystick driver module itself, most
+usually you'll have an analog joystick::
 
 	modprobe analog
-	
-  For automatic module loading, something like this might work - tailor to
-your needs:
+
+For automatic module loading, something like this might work - tailor to
+your needs::
 
 	alias tty-ldisc-2 serport
 	alias char-major-13 input
 	above input joydev ns558 analog
 	options analog map=gamepad,none,2btn
 
-2.5 Verifying that it works
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  For testing the joystick driver functionality, there is the jstest
-program in the utilities package. You run it by typing:
+Verifying that it works
+-----------------------
+
+For testing the joystick driver functionality, there is the jstest
+program in the utilities package. You run it by typing::
 
 	jstest /dev/input/js0
 
-  And it should show a line with the joystick values, which update as you
+And it should show a line with the joystick values, which update as you
 move the stick, and press its buttons. The axes should all be zero when the
 joystick is in the center position. They should not jitter by themselves to
 other close values, and they also should be steady in any other position of
 the stick. They should have the full range from -32767 to 32767. If all this
 is met, then it's all fine, and you can play the games. :)
 
-  If it's not, then there might be a problem. Try to calibrate the joystick,
+If it's not, then there might be a problem. Try to calibrate the joystick,
 and if it still doesn't work, read the drivers section of this file, the
 troubleshooting section, and the FAQ.
 
-2.6. Calibration
-~~~~~~~~~~~~~~~~
-  For most joysticks you won't need any manual calibration, since the
+Calibration
+-----------
+
+For most joysticks you won't need any manual calibration, since the
 joystick should be autocalibrated by the driver automagically. However, with
 some analog joysticks, that either do not use linear resistors, or if you
-want better precision, you can use the jscal program
+want better precision, you can use the jscal program::
 
 	jscal -c /dev/input/js0
 
- included in the joystick package to set better correction coefficients than
+included in the joystick package to set better correction coefficients than
 what the driver would choose itself.
 
-  After calibrating the joystick you can verify if you like the new
+After calibrating the joystick you can verify if you like the new
 calibration using the jstest command, and if you do, you then can save the
-correction coefficients into a file
+correction coefficients into a file::
 
 	jscal -p /dev/input/js0 > /etc/joystick.cal
 
-  And add a line to your rc script executing that file
+And add a line to your rc script executing that file::
 
 	source /etc/joystick.cal
 
-  This way, after the next reboot your joystick will remain calibrated. You
-can also add the jscal -p line to your shutdown script.
+This way, after the next reboot your joystick will remain calibrated. You
+can also add the ``jscal -p`` line to your shutdown script.
 
 
-3. HW specific driver information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+HW specific driver information
+==============================
+
 In this section each of the separate hardware specific drivers is described.
 
-3.1 Analog joysticks
-~~~~~~~~~~~~~~~~~~~~
-  The analog.c uses the standard analog inputs of the gameport, and thus
+Analog joysticks
+----------------
+
+The analog.c uses the standard analog inputs of the gameport, and thus
 supports all standard joysticks and gamepads. It uses a very advanced
 routine for this, allowing for data precision that can't be found on any
 other system.
 
-  It also supports extensions like additional hats and buttons compatible
+It also supports extensions like additional hats and buttons compatible
 with CH Flightstick Pro, ThrustMaster FCS or 6 and 8 button gamepads. Saitek
 Cyborg 'digital' joysticks are also supported by this driver, because
 they're basically souped up CHF sticks.
 
-  However the only types that can be autodetected are:
+However the only types that can be autodetected are:
 
 * 2-axis, 4-button joystick
 * 3-axis, 4-button joystick
 * 4-axis, 4-button joystick
 * Saitek Cyborg 'digital' joysticks
 
-  For other joystick types (more/less axes, hats, and buttons) support
+For other joystick types (more/less axes, hats, and buttons) support
 you'll need to specify the types either on the kernel command line or on the
 module command line, when inserting analog into the kernel. The
-parameters are:
+parameters are::
 
 	analog.map=<type1>,<type2>,<type3>,....
 
-  'type' is type of the joystick from the table below, defining joysticks
+'type' is type of the joystick from the table below, defining joysticks
 present on gameports in the system, starting with gameport0, second 'type'
 entry defining joystick on gameport1 and so on.
 
-	Type     | Meaning
-	-----------------------------------
-	none     | No analog joystick on that port
-	auto     | Autodetect joystick
-	2btn     | 2-button n-axis joystick
-	y-joy    | Two 2-button 2-axis joysticks on an Y-cable
-	y-pad    | Two 2-button 2-axis gamepads on an Y-cable
-	fcs      | Thrustmaster FCS compatible joystick
-	chf      | Joystick with a CH Flightstick compatible hat
-	fullchf  | CH Flightstick compatible with two hats and 6 buttons
-	gamepad  | 4/6-button n-axis gamepad
-	gamepad8 | 8-button 2-axis gamepad
+	========= =====================================================
+	Type      Meaning
+	========= =====================================================
+	none      No analog joystick on that port
+	auto      Autodetect joystick
+	2btn      2-button n-axis joystick
+	y-joy     Two 2-button 2-axis joysticks on an Y-cable
+	y-pad     Two 2-button 2-axis gamepads on an Y-cable
+	fcs       Thrustmaster FCS compatible joystick
+	chf       Joystick with a CH Flightstick compatible hat
+	fullchf   CH Flightstick compatible with two hats and 6 buttons
+	gamepad   4/6-button n-axis gamepad
+	gamepad8  8-button 2-axis gamepad
+	========= =====================================================
 
-  In case your joystick doesn't fit in any of the above categories, you can
+In case your joystick doesn't fit in any of the above categories, you can
 specify the type as a number by combining the bits in the table below. This
 is not recommended unless you really know what are you doing. It's not
 dangerous, but not simple either.
 
-	Bit | Meaning
-	--------------------------
-	 0  | Axis X1
-	 1  | Axis Y1
-	 2  | Axis X2
-	 3  | Axis Y2
-	 4  | Button A
-	 5  | Button B
-	 6  | Button C
-	 7  | Button D
-	 8  | CHF Buttons X and Y
-	 9  | CHF Hat 1
-	10  | CHF Hat 2
-	11  | FCS Hat
-	12  | Pad Button X
-	13  | Pad Button Y
-	14  | Pad Button U
-	15  | Pad Button V
-	16  | Saitek F1-F4 Buttons
-	17  | Saitek Digital Mode
-	19  | GamePad
-	20  | Joy2 Axis X1
-	21  | Joy2 Axis Y1
-	22  | Joy2 Axis X2
-	23  | Joy2 Axis Y2
-	24  | Joy2 Button A
-	25  | Joy2 Button B
-	26  | Joy2 Button C
-	27  | Joy2 Button D
-	31  | Joy2 GamePad
+	==== =========================
+	Bit  Meaning
+	==== =========================
+	 0   Axis X1
+	 1   Axis Y1
+	 2   Axis X2
+	 3   Axis Y2
+	 4   Button A
+	 5   Button B
+	 6   Button C
+	 7   Button D
+	 8   CHF Buttons X and Y
+	 9   CHF Hat 1
+	10   CHF Hat 2
+	11   FCS Hat
+	12   Pad Button X
+	13   Pad Button Y
+	14   Pad Button U
+	15   Pad Button V
+	16   Saitek F1-F4 Buttons
+	17   Saitek Digital Mode
+	19   GamePad
+	20   Joy2 Axis X1
+	21   Joy2 Axis Y1
+	22   Joy2 Axis X2
+	23   Joy2 Axis Y2
+	24   Joy2 Button A
+	25   Joy2 Button B
+	26   Joy2 Button C
+	27   Joy2 Button D
+	31   Joy2 GamePad
+	==== =========================
 
-3.2 Microsoft SideWinder joysticks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c
+Microsoft SideWinder joysticks
+------------------------------
+
+Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c
 module. All currently supported joysticks:
 
 * Microsoft SideWinder 3D Pro
 * Microsoft SideWinder Force Feedback Pro
 * Microsoft SideWinder Force Feedback Wheel
-* Microsoft SideWinder FreeStyle Pro 
+* Microsoft SideWinder FreeStyle Pro
 * Microsoft SideWinder GamePad (up to four, chained)
-* Microsoft SideWinder Precision Pro 
-* Microsoft SideWinder Precision Pro USB 
+* Microsoft SideWinder Precision Pro
+* Microsoft SideWinder Precision Pro USB
 
-  are autodetected, and thus no module parameters are needed.
+are autodetected, and thus no module parameters are needed.
 
-  There is one caveat with the 3D Pro. There are 9 buttons reported,
+There is one caveat with the 3D Pro. There are 9 buttons reported,
 although the joystick has only 8. The 9th button is the mode switch on the
 rear side of the joystick. However, moving it, you'll reset the joystick,
 and make it unresponsive for about a one third of a second. Furthermore, the
 joystick will also re-center itself, taking the position it was in during
 this time as a new center position. Use it if you want, but think first.
 
-  The SideWinder Standard is not a digital joystick, and thus is supported
-by the analog driver described above. 
+The SideWinder Standard is not a digital joystick, and thus is supported
+by the analog driver described above.
 
-3.3 Logitech ADI devices
-~~~~~~~~~~~~~~~~~~~~~~~~
-  Logitech ADI protocol is supported by the adi.c module. It should support
+Logitech ADI devices
+--------------------
+
+Logitech ADI protocol is supported by the adi.c module. It should support
 any Logitech device using this protocol. This includes, but is not limited
 to:
 
@@ -279,20 +299,21 @@ to:
 * Logitech WingMan GamePad Extreme
 * Logitech WingMan Extreme Digital 3D
 
-  ADI devices are autodetected, and the driver supports up to two (any
+ADI devices are autodetected, and the driver supports up to two (any
 combination of) devices on a single gameport, using an Y-cable or chained
 together.
 
-  Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan
+Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan
 Extreme and Logitech WingMan ThunderPad are not digital joysticks and are
 handled by the analog driver described above. Logitech WingMan Warrior and
 Logitech Magellan are supported by serial drivers described below.  Logitech
 WingMan Force and Logitech WingMan Formula Force are supported by the
 I-Force driver described below. Logitech CyberMan is not supported yet.
 
-3.4 Gravis GrIP
-~~~~~~~~~~~~~~~
-  Gravis GrIP protocol is supported by the grip.c module. It currently
+Gravis GrIP
+-----------
+
+Gravis GrIP protocol is supported by the grip.c module. It currently
 supports:
 
 * Gravis GamePad Pro
@@ -300,7 +321,7 @@ supports:
 * Gravis Xterminator
 * Gravis Xterminator DualControl
 
-  All these devices are autodetected, and you can even use any combination
+All these devices are autodetected, and you can even use any combination
 of up to two of these pads either chained together or using an Y-cable on a
 single gameport.
 
@@ -308,9 +329,10 @@ GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is
 supported by the stinger driver. Other Gravis joysticks are supported by the
 analog driver.
 
-3.5 FPGaming A3D and MadCatz A3D
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The Assassin 3D protocol created by FPGaming, is used both by FPGaming
+FPGaming A3D and MadCatz A3D
+----------------------------
+
+The Assassin 3D protocol created by FPGaming, is used both by FPGaming
 themselves and is licensed to MadCatz. A3D devices are supported by the
 a3d.c module. It currently supports:
 
@@ -318,125 +340,139 @@ a3d.c module. It currently supports:
 * MadCatz Panther
 * MadCatz Panther XL
 
-  All these devices are autodetected. Because the Assassin 3D and the Panther
+All these devices are autodetected. Because the Assassin 3D and the Panther
 allow connecting analog joysticks to them, you'll need to load the analog
 driver as well to handle the attached joysticks.
 
-  The trackball should work with USB mousedev module as a normal mouse. See
+The trackball should work with USB mousedev module as a normal mouse. See
 the USB documentation for how to setup an USB mouse.
 
-3.6 ThrustMaster DirectConnect (BSP)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The TM DirectConnect (BSP) protocol is supported by the tmdc.c
+ThrustMaster DirectConnect (BSP)
+--------------------------------
+
+The TM DirectConnect (BSP) protocol is supported by the tmdc.c
 module. This includes, but is not limited to:
 
 * ThrustMaster Millennium 3D Interceptor
 * ThrustMaster 3D Rage Pad
 * ThrustMaster Fusion Digital Game Pad
 
-  Devices not directly supported, but hopefully working are:
+Devices not directly supported, but hopefully working are:
 
 * ThrustMaster FragMaster
 * ThrustMaster Attack Throttle
 
-  If you have one of these, contact me.
+If you have one of these, contact me.
 
-  TMDC devices are autodetected, and thus no parameters to the module
+TMDC devices are autodetected, and thus no parameters to the module
 are needed. Up to two TMDC devices can be connected to one gameport, using
 an Y-cable.
 
-3.7 Creative Labs Blaster
-~~~~~~~~~~~~~~~~~~~~~~~~~
-  The Blaster protocol is supported by the cobra.c module. It supports only
+Creative Labs Blaster
+---------------------
+
+The Blaster protocol is supported by the cobra.c module. It supports only
 the:
 
 * Creative Blaster GamePad Cobra
 
-  Up to two of these can be used on a single gameport, using an Y-cable.
+Up to two of these can be used on a single gameport, using an Y-cable.
 
-3.8 Genius Digital joysticks 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The Genius digitally communicating joysticks are supported by the gf2k.c
+Genius Digital joysticks
+------------------------
+
+The Genius digitally communicating joysticks are supported by the gf2k.c
 module. This includes:
 
-* Genius Flight2000 F-23 joystick 
-* Genius Flight2000 F-31 joystick 
+* Genius Flight2000 F-23 joystick
+* Genius Flight2000 F-31 joystick
 * Genius G-09D gamepad
 
-  Other Genius digital joysticks are not supported yet, but support can be
+Other Genius digital joysticks are not supported yet, but support can be
 added fairly easily.
 
-3.9 InterAct Digital joysticks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The InterAct digitally communicating joysticks are supported by the
+InterAct Digital joysticks
+--------------------------
+
+The InterAct digitally communicating joysticks are supported by the
 interact.c module. This includes:
 
 * InterAct HammerHead/FX gamepad
-* InterAct ProPad8 gamepad 
+* InterAct ProPad8 gamepad
 
-  Other InterAct digital joysticks are not supported yet, but support can be 
+Other InterAct digital joysticks are not supported yet, but support can be
 added fairly easily.
 
-3.10 PDPI Lightning 4 gamecards
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  PDPI Lightning 4 gamecards are supported by the lightning.c module.
+PDPI Lightning 4 gamecards
+--------------------------
+
+PDPI Lightning 4 gamecards are supported by the lightning.c module.
 Once the module is loaded, the analog driver can be used to handle the
 joysticks. Digitally communicating joystick will work only on port 0, while
 using Y-cables, you can connect up to 8 analog joysticks to a single L4
 card, 16 in case you have two in your system.
 
-3.11 Trident 4DWave / Aureal Vortex
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipsets
+Trident 4DWave / Aureal Vortex
+------------------------------
+
+Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipsets
 provide an "Enhanced Game Port" mode where the soundcard handles polling the
 joystick.  This mode is supported by the pcigame.c module. Once loaded the
 analog driver can use the enhanced features of these gameports..
 
-3.13 Crystal SoundFusion
-~~~~~~~~~~~~~~~~~~~~~~~~
-  Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game
+Crystal SoundFusion
+-------------------
+
+Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game
 Port", much like the 4DWave or Vortex above. This, and also the normal mode
 for the port of the SoundFusion is supported by the cs461x.c module.
 
-3.14 SoundBlaster Live!
-~~~~~~~~~~~~~~~~~~~~~~~~
-  The Live! has a special PCI gameport, which, although it doesn't provide
+SoundBlaster Live!
+------------------
+
+The Live! has a special PCI gameport, which, although it doesn't provide
 any "Enhanced" stuff like 4DWave and friends, is quite a bit faster than
 its ISA counterparts. It also requires special support, hence the
 emu10k1-gp.c module for it instead of the normal ns558.c one.
 
-3.15 SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  These PCI soundcards have specific gameports. They are handled by the
+SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes
+------------------------------------------------------------------------
+
+These PCI soundcards have specific gameports. They are handled by the
 sound drivers themselves. Make sure you select gameport support in the
 joystick menu and sound card support in the sound menu for your appropriate
 card.
 
-3.16 Amiga
-~~~~~~~~~~
-  Amiga joysticks, connected to an Amiga, are supported by the amijoy.c
-driver. Since they can't be autodetected, the driver has a command line.
+Amiga
+-----
+
+Amiga joysticks, connected to an Amiga, are supported by the amijoy.c
+driver. Since they can't be autodetected, the driver has a command line:
 
 	amijoy.map=<a>,<b>
 
-  a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of
+a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of
 the Amiga.
 
-	Value | Joystick type
-	---------------------
-	  0   | None
-	  1   | 1-button digital joystick
+	====== ===========================
+	Value  Joystick type
+	====== ===========================
+	  0    None
+	  1    1-button digital joystick
+	====== ===========================
 
-  No more joystick types are supported now, but that should change in the
+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.
 
-3.17 Game console and 8-bit pads and joysticks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-See joystick-parport.txt for more info.
+Game console and 8-bit pads and joysticks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-3.18 SpaceTec/LabTec devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  SpaceTec serial devices communicate using the SpaceWare protocol. It is
+See :ref:`joystick-parport` for more info.
+
+SpaceTec/LabTec devices
+-----------------------
+
+SpaceTec serial devices communicate using the SpaceWare protocol. It is
 supported by the spaceorb.c and spaceball.c drivers. The devices currently
 supported by spaceorb.c are:
 
@@ -447,43 +483,47 @@ Devices currently supported by spaceball.c are:
 
 * SpaceTec SpaceBall 4000 FLX
 
-  In addition to having the spaceorb/spaceball and serport modules in the
+In addition to having the spaceorb/spaceball and serport modules in the
 kernel, you also need to attach a serial port to it. to do that, run the
-inputattach program:
+inputattach program::
 
 	inputattach --spaceorb /dev/tts/x &
-or
+
+or::
+
 	inputattach --spaceball /dev/tts/x &
 
 where /dev/tts/x is the serial port which the device is connected to. After
 doing this, the device will be reported and will start working.
 
-  There is one caveat with the SpaceOrb. The button #6, the on the bottom
+There is one caveat with the SpaceOrb. The button #6, the on the bottom
 side of the orb, although reported as an ordinary button, causes internal
 recentering of the spaceorb, moving the zero point to the position in which
 the ball is at the moment of pressing the button. So, think first before
 you bind it to some other function.
 
-SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet. 
+SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet.
 
-3.19 Logitech SWIFT devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The SWIFT serial protocol is supported by the warrior.c module. It
+Logitech SWIFT devices
+----------------------
+
+The SWIFT serial protocol is supported by the warrior.c module. It
 currently supports only the:
 
 * Logitech WingMan Warrior
 
 but in the future, Logitech CyberMan (the original one, not CM2) could be
 supported as well. To use the module, you need to run inputattach after you
-insert/compile the module into your kernel:
+insert/compile the module into your kernel::
 
 	inputattach --warrior /dev/tts/x &
 
 /dev/tts/x is the serial port your Warrior is attached to.
 
-3.20 Magellan / Space Mouse
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space
+Magellan / Space Mouse
+----------------------
+
+The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space
 Systems), for many other companies (Logitech, HP, ...) is supported by the
 joy-magellan module. It currently supports only the:
 
@@ -492,94 +532,99 @@ joy-magellan module. It currently supports only the:
 
 models, the additional buttons on the 'Plus' versions are not supported yet.
 
-  To use it, you need to attach the serial port to the driver using the
+To use it, you need to attach the serial port to the driver using the::
 
 	inputattach --magellan /dev/tts/x &
 
 command. After that the Magellan will be detected, initialized, will beep,
 and the /dev/input/jsX device should become usable.
 
-3.21 I-Force devices 
-~~~~~~~~~~~~~~~~~~~~
-  All I-Force devices are supported by the iforce module. This includes:
+I-Force devices
+---------------
+
+All I-Force devices are supported by the iforce module. This includes:
 
 * AVB Mag Turbo Force
 * AVB Top Shot Pegasus
 * AVB Top Shot Force Feedback Racing Wheel
 * Logitech WingMan Force
-* Logitech WingMan Force Wheel 
+* Logitech WingMan Force Wheel
 * Guillemot Race Leader Force Feedback
 * Guillemot Force Feedback Racing Wheel
 * Thrustmaster Motor Sport GT
 
-  To use it, you need to attach the serial port to the driver using the
+To use it, you need to attach the serial port to the driver using the::
 
 	inputattach --iforce /dev/tts/x &
 
 command. After that the I-Force device will be detected, and the
 /dev/input/jsX device should become usable.
 
-  In case you're using the device via the USB port, the inputattach command
+In case you're using the device via the USB port, the inputattach command
 isn't needed.
 
-  The I-Force driver now supports force feedback via the event interface.
+The I-Force driver now supports force feedback via the event interface.
 
-  Please note that Logitech WingMan *3D devices are _not_ supported by this
+Please note that Logitech WingMan 3D devices are _not_ supported by this
 module, rather by hid. Force feedback is not supported for those devices.
 Logitech gamepads are also hid devices.
 
-3.22 Gravis Stinger gamepad 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The Gravis Stinger serial port gamepad, designed for use with laptop
+Gravis Stinger gamepad
+----------------------
+
+The Gravis Stinger serial port gamepad, designed for use with laptop
 computers, is supported by the stinger.c module. To use it, attach the
-serial port to the driver using:
+serial port to the driver using::
 
-        inputattach --stinger /dev/tty/x &
+	inputattach --stinger /dev/tty/x &
 
 where x is the number of the serial port.
 
-4. Troubleshooting
-~~~~~~~~~~~~~~~~~~
-  There is quite a high probability that you run into some problems. For
+Troubleshooting
+===============
+
+There is quite a high probability that you run into some problems. For
 testing whether the driver works, if in doubt, use the jstest utility in
 some of its modes. The most useful modes are "normal" - for the 1.x
-interface, and "old" for the "0.x" interface. You run it by typing:
+interface, and "old" for the "0.x" interface. You run it by typing::
 
 	jstest --normal /dev/input/js0
 	jstest --old    /dev/input/js0
 
-  Additionally you can do a test with the evtest utility:
+Additionally you can do a test with the evtest utility::
 
 	evtest /dev/input/event0
 
-  Oh, and read the FAQ! :)
+Oh, and read the FAQ! :)
 
-5. FAQ
-~~~~~~
-Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the
-   cause?
-A: The device files don't exist. Create them (see section 2.2).
+FAQ
+===
 
-Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick
-   or pad that uses a 9-pin D-type cannon connector to the serial port of my
-   PC?
-A: Yes, it is possible, but it'll burn your serial port or the pad. It
-   won't work, of course.
+:Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the
+    cause?
+:A: The device files don't exist. Create them (see section 2.2).
 
-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.
+:Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick
+    or pad that uses a 9-pin D-type cannon connector to the serial port of my
+    PC?
+:A: Yes, it is possible, but it'll burn your serial port or the pad. It
+    won't work, of course.
 
-6. Programming Interface
-~~~~~~~~~~~~~~~~~~~~~~~~
-  The 1.0 driver uses a new, event based approach to the joystick driver.
+: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.
+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
-- 
2.9.3

[PATCH v2 20/33] docs: input/joystick-parport: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/joystick-parport.txt | 708 ++++++++++++++++---------------
 1 file changed, 370 insertions(+), 338 deletions(-)

diff --git a/Documentation/input/joystick-parport.txt b/Documentation/input/joystick-parport.txt
index 56870c70a796..0aa0fb17bf48 100644
--- a/Documentation/input/joystick-parport.txt
+++ b/Documentation/input/joystick-parport.txt
@@ -1,333 +1,349 @@
-		    Linux Joystick parport drivers v2.0
-	       (c) 1998-2000 Vojtech Pavlik <vojtech@ucw.cz>
-	       (c) 1998 Andree Borrmann <a.borrmann@tu-bs.de>
-			     Sponsored by SuSE
-----------------------------------------------------------------------------
-
-0. Disclaimer
-~~~~~~~~~~~~~
-  Any information in this file is provided as-is, without any guarantee that
+.. include:: <isonum.txt>
+
+.. _joystick-parport:
+
+===================================
+Linux Joystick parport drivers v2.0
+===================================
+
+:Copyright: |copy| 1998-2000 Vojtech Pavlik <vojtech@ucw.cz>
+:Copyright: |copy| 1998 Andree Borrmann <a.borrmann@tu-bs.de>
+
+
+Sponsored by SuSE
+
+Disclaimer
+==========
+
+Any information in this file is provided as-is, without any guarantee that
 it will be true. So, use it at your own risk. The possible damages that can
 happen include burning your parallel port, and/or the sticks and joystick
 and maybe even more. Like when a lightning kills you it is not our problem.
 
-1. Intro
-~~~~~~~~
-  The joystick parport drivers are used for joysticks and gamepads not
+Intro
+=====
+
+The joystick parport drivers are used for joysticks and gamepads not
 originally designed for PCs and other computers Linux runs on. Because of
 that, PCs usually lack the right ports to connect these devices to. Parallel
 port, because of its ability to change single bits at will, and providing
 both output and input bits is the most suitable port on the PC for
 connecting such devices.
 
-2. Devices supported
-~~~~~~~~~~~~~~~~~~~~
-  Many console and 8-bit computer gamepads and joysticks are supported. The
+Devices supported
+=================
+
+Many console and 8-bit computer gamepads and joysticks are supported. The
 following subsections discuss usage of each.
 
-2.1 NES and SNES
-~~~~~~~~~~~~~~~~
-  The Nintendo Entertainment System and Super Nintendo Entertainment System
+NES and SNES
+------------
+
+The Nintendo Entertainment System and Super Nintendo Entertainment System
 gamepads are widely available, and easy to get. Also, they are quite easy to
 connect to a PC, and don't need much processing speed (108 us for NES and
 165 us for SNES, compared to about 1000 us for PC gamepads) to communicate
 with them.
 
-  All NES and SNES use the same synchronous serial protocol, clocked from
+All NES and SNES use the same synchronous serial protocol, clocked from
 the computer's side (and thus timing insensitive). To allow up to 5 NES
 and/or SNES gamepads and/or SNES mice connected to the parallel port at once,
 the output lines of the parallel port are shared, while one of 5 available
 input lines is assigned to each gamepad.
 
-  This protocol is handled by the gamecon.c driver, so that's the one
+This protocol is handled by the gamecon.c driver, so that's the one
 you'll use for NES, SNES gamepads and SNES mice.
 
-  The main problem with PC parallel ports is that they don't have +5V power
+The main problem with PC parallel ports is that they don't have +5V power
 source on any of their pins. So, if you want a reliable source of power
 for your pads, use either keyboard or joystick port, and make a pass-through
 cable. You can also pull the power directly from the power supply (the red
 wire is +5V).
 
-  If you want to use the parallel port only, you can take the power is from
+If you want to use the parallel port only, you can take the power is from
 some data pin. For most gamepad and parport implementations only one pin is
 needed, and I'd recommend pin 9 for that, the highest data bit. On the other
 hand, if you are not planning to use anything else than NES / SNES on the
-port, anything between and including pin 4 and pin 9 will work.
+port, anything between and including pin 4 and pin 9 will work::
 
-(pin 9) -----> Power
+    (pin 9) -----> Power
 
-  Unfortunately, there are pads that need a lot more of power, and parallel
+Unfortunately, there are pads that need a lot more of power, and parallel
 ports that can't give much current through the data pins. If this is your
 case, you'll need to use diodes (as a prevention of destroying your parallel
-port), and combine the currents of two or more data bits together.
+port), and combine the currents of two or more data bits together::
 
-	   Diodes
-(pin 9) ----|>|-------+------> Power
-		      |
-(pin 8) ----|>|-------+
-		      |
-(pin 7) ----|>|-------+
-		      |
- <and so on>          :
-		      |
-(pin 4) ----|>|-------+
+	      Diodes
+    (pin 9) ----|>|-------+------> Power
+			|
+    (pin 8) ----|>|-------+
+			|
+    (pin 7) ----|>|-------+
+			|
+    <and so on>         :
+			|
+    (pin 4) ----|>|-------+
 
-  Ground is quite easy. On PC's parallel port the ground is on any of the
-pins from pin 18 to pin 25. So use any pin of these you like for the ground.
+Ground is quite easy. On PC's parallel port the ground is on any of the
+pins from pin 18 to pin 25. So use any pin of these you like for the ground::
 
-(pin 18) -----> Ground
+    (pin 18) -----> Ground
 
-  NES and SNES pads have two input bits, Clock and Latch, which drive the
+NES and SNES pads have two input bits, Clock and Latch, which drive the
 serial transfer. These are connected to pins 2 and 3 of the parallel port,
-respectively.
+respectively::
 
-(pin 2) -----> Clock
-(pin 3) -----> Latch
+    (pin 2) -----> Clock
+    (pin 3) -----> Latch
 
-  And the last thing is the NES / SNES data wire. Only that isn't shared and
-each pad needs its own data pin. The parallel port pins are:
+And the last thing is the NES / SNES data wire. Only that isn't shared and
+each pad needs its own data pin. The parallel port pins are::
 
-(pin 10) -----> Pad 1 data
-(pin 11) -----> Pad 2 data
-(pin 12) -----> Pad 3 data
-(pin 13) -----> Pad 4 data
-(pin 15) -----> Pad 5 data
+    (pin 10) -----> Pad 1 data
+    (pin 11) -----> Pad 2 data
+    (pin 12) -----> Pad 3 data
+    (pin 13) -----> Pad 4 data
+    (pin 15) -----> Pad 5 data
 
-  Note that pin 14 is not used, since it is not an input pin on the parallel
+Note that pin 14 is not used, since it is not an input pin on the parallel
 port.
 
-  This is everything you need on the PC's side of the connection, now on to
+This is everything you need on the PC's side of the connection, now on to
 the gamepads side. The NES and SNES have different connectors. Also, there
 are quite a lot of NES clones, and because Nintendo used proprietary
 connectors for their machines, the cloners couldn't and used standard D-Cannon
 connectors. Anyway, if you've got a gamepad, and it has buttons A, B, Turbo
 A, Turbo B, Select and Start, and is connected through 5 wires, then it is
 either a NES or NES clone and will work with this connection. SNES gamepads
-also use 5 wires, but have more buttons. They will work as well, of course.
+also use 5 wires, but have more buttons. They will work as well, of course::
 
-Pinout for NES gamepads                 Pinout for SNES gamepads and mice
+  Pinout for NES gamepads                 Pinout for SNES gamepads and mice
 
-	   +----> Power                   +-----------------------\
-	   |                            7 | o  o  o  o |  x  x  o  | 1
- 5 +---------+  7                         +-----------------------/
-   | x  x  o   \                            |  |  |  |          |
-   | o  o  o  o |                           |  |  |  |          +-> Ground
- 4 +------------+ 1                         |  |  |  +------------> Data
-     |  |  |  |                             |  |  +---------------> Latch
-     |  |  |  +-> Ground                    |  +------------------> Clock
-     |  |  +----> Clock                     +---------------------> Power
-     |  +-------> Latch
-     +----------> Data
+             +----> Power                   +-----------------------\
+             |                            7 | o  o  o  o |  x  x  o  | 1
+   5 +---------+  7                         +-----------------------/
+     | x  x  o   \                            |  |  |  |          |
+     | o  o  o  o |                           |  |  |  |          +-> Ground
+   4 +------------+ 1                         |  |  |  +------------> Data
+       |  |  |  |                             |  |  +---------------> Latch
+       |  |  |  +-> Ground                    |  +------------------> Clock
+       |  |  +----> Clock                     +---------------------> Power
+       |  +-------> Latch
+       +----------> Data
 
-Pinout for NES clone (db9) gamepads     Pinout for NES clone (db15) gamepads
+  Pinout for NES clone (db9) gamepads     Pinout for NES clone (db15) gamepads
 
-	+---------> Clock                    +-----------------> Data
-	| +-------> Latch                    |             +---> Ground
-	| | +-----> Data                     |             |
-	| | |                              ___________________
+        +---------> Clock                    +-----------------> Data
+        | +-------> Latch                    |             +---> Ground
+        | | +-----> Data                     |             |
+        | | |                              ___________________
     _____________                        8 \ o x x x x x x o / 1
   5 \ x o o o x / 1                         \ o x x o x x o /
      \ x o x o /                          15 `~~~~~~~~~~~~~' 9
     9 `~~~~~~~' 6                             |     |     |
-	 |   |                                |     |     +----> Clock
-	 |   +----> Power                     |     +----------> Latch
-	 +--------> Ground                    +----------------> Power
+         |   |                                |     |     +----> Clock
+         |   +----> Power                     |     +----------> Latch
+         +--------> Ground                    +----------------> Power
 
-2.2 Multisystem joysticks
-~~~~~~~~~~~~~~~~~~~~~~~~~
-  In the era of 8-bit machines, there was something like de-facto standard
+Multisystem joysticks
+---------------------
+
+In the era of 8-bit machines, there was something like de-facto standard
 for joystick ports. They were all digital, and all used D-Cannon 9 pin
 connectors (db9). Because of that, a single joystick could be used without
 hassle on Atari (130, 800XE, 800XL, 2600, 7200), Amiga, Commodore C64,
 Amstrad CPC, Sinclair ZX Spectrum and many other machines. That's why these
 joysticks are called "Multisystem".
 
-  Now their pinout:
+Now their pinout::
 
-      +---------> Right
-      | +-------> Left
-      | | +-----> Down
-      | | | +---> Up
-      | | | |
-  _____________
-5 \ x o o o o / 1
-   \ x o x o /
-  9 `~~~~~~~' 6
-       |   |
-       |   +----> Button
-       +--------> Ground
+        +---------> Right
+        | +-------> Left
+        | | +-----> Down
+        | | | +---> Up
+        | | | |
+    _____________
+  5 \ x o o o o / 1
+     \ x o x o /
+    9 `~~~~~~~' 6
+         |   |
+         |   +----> Button
+         +--------> Ground
 
-  However, as time passed, extensions to this standard developed, and these
-were not compatible with each other:
+However, as time passed, extensions to this standard developed, and these
+were not compatible with each other::
 
 
-	Atari 130, 800/XL/XE		   MSX
+          Atari 130, 800/XL/XE                   MSX
 
-					 +-----------> Power
-      +---------> Right                  | +---------> Right
-      | +-------> Left                   | | +-------> Left
-      | | +-----> Down                   | | | +-----> Down
-      | | | +---> Up                     | | | | +---> Up
-      | | | |                            | | | | |
-  _____________                        _____________
-5 \ x o o o o / 1                    5 \ o o o o o / 1
-   \ x o o o /                          \ o o o o /
-  9 `~~~~~~~' 6                        9 `~~~~~~~' 6
-       | | |                              | | | |
-       | | +----> Button                  | | | +----> Button 1
-       | +------> Power                   | | +------> Button 2
-       +--------> Ground                  | +--------> Output 3
-					  +----------> Ground
+                                           +-----------> Power
+        +---------> Right                  | +---------> Right
+        | +-------> Left                   | | +-------> Left
+        | | +-----> Down                   | | | +-----> Down
+        | | | +---> Up                     | | | | +---> Up
+        | | | |                            | | | | |
+    _____________                        _____________
+  5 \ x o o o o / 1                    5 \ o o o o o / 1
+     \ x o o o /                          \ o o o o /
+    9 `~~~~~~~' 6                        9 `~~~~~~~' 6
+         | | |                              | | | |
+         | | +----> Button                  | | | +----> Button 1
+         | +------> Power                   | | +------> Button 2
+         +--------> Ground                  | +--------> Output 3
+                                            +----------> Ground
 
-	Amstrad CPC			   Commodore C64
+          Amstrad CPC                           Commodore C64
 
-					 +-----------> Analog Y
-      +---------> Right                  | +---------> Right
-      | +-------> Left                   | | +-------> Left
-      | | +-----> Down                   | | | +-----> Down
-      | | | +---> Up                     | | | | +---> Up
-      | | | |                            | | | | |
-  _____________                        _____________
-5 \ x o o o o / 1                    5 \ o o o o o / 1
-   \ x o o o /                          \ o o o o /
-  9 `~~~~~~~' 6                        9 `~~~~~~~' 6
-       | | |                              | | | |
-       | | +----> Button 1                | | | +----> Button
-       | +------> Button 2                | | +------> Power
-       +--------> Ground                  | +--------> Ground
-					  +----------> Analog X
+                                           +-----------> Analog Y
+        +---------> Right                  | +---------> Right
+        | +-------> Left                   | | +-------> Left
+        | | +-----> Down                   | | | +-----> Down
+        | | | +---> Up                     | | | | +---> Up
+        | | | |                            | | | | |
+    _____________                        _____________
+  5 \ x o o o o / 1                    5 \ o o o o o / 1
+     \ x o o o /                          \ o o o o /
+    9 `~~~~~~~' 6                        9 `~~~~~~~' 6
+         | | |                              | | | |
+         | | +----> Button 1                | | | +----> Button
+         | +------> Button 2                | | +------> Power
+         +--------> Ground                  | +--------> Ground
+                                            +----------> Analog X
 
-	Sinclair Spectrum +2A/+3           Amiga 1200
-                                     
-    +-----------> Up                     +-----------> Button 3
-    | +---------> Fire                   | +---------> Right
-    | |                                  | | +-------> Left
-    | |   +-----> Ground                 | | | +-----> Down
-    | |   |                              | | | | +---> Up
-    | |   |                              | | | | |
-  _____________                        _____________
-5 \ o o x o x / 1                    5 \ o o o o o / 1
-   \ o o o o /                          \ o o o o /
-  9 `~~~~~~~' 6                        9 `~~~~~~~' 6
-     | | | |                              | | | |
-     | | | +----> Right                   | | | +----> Button 1
-     | | +------> Left                    | | +------> Power
-     | +--------> Ground                  | +--------> Ground
-     +----------> Down                    +----------> Button 2
+          Sinclair Spectrum +2A/+3           Amiga 1200
+
+      +-----------> Up                     +-----------> Button 3
+      | +---------> Fire                   | +---------> Right
+      | |                                  | | +-------> Left
+      | |   +-----> Ground                 | | | +-----> Down
+      | |   |                              | | | | +---> Up
+      | |   |                              | | | | |
+    _____________                        _____________
+  5 \ o o x o x / 1                    5 \ o o o o o / 1
+     \ o o o o /                          \ o o o o /
+    9 `~~~~~~~' 6                        9 `~~~~~~~' 6
+       | | | |                              | | | |
+       | | | +----> Right                   | | | +----> Button 1
+       | | +------> Left                    | | +------> Power
+       | +--------> Ground                  | +--------> Ground
+       +----------> Down                    +----------> Button 2
 
   And there were many others.
 
-2.2.1 Multisystem joysticks using db9.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  For the Multisystem joysticks, and their derivatives, the db9.c driver
+Multisystem joysticks using db9.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For the Multisystem joysticks, and their derivatives, the db9.c driver
 was written. It allows only one joystick / gamepad per parallel port, but
 the interface is easy to build and works with almost anything.
 
-  For the basic 1-button Multisystem joystick you connect its wires to the
-parallel port like this:
+For the basic 1-button Multisystem joystick you connect its wires to the
+parallel port like this::
 
-(pin  1) -----> Power
-(pin 18) -----> Ground
+    (pin  1) -----> Power
+    (pin 18) -----> Ground
 
-(pin  2) -----> Up
-(pin  3) -----> Down
-(pin  4) -----> Left
-(pin  5) -----> Right
-(pin  6) -----> Button 1
+    (pin  2) -----> Up
+    (pin  3) -----> Down
+    (pin  4) -----> Left
+    (pin  5) -----> Right
+    (pin  6) -----> Button 1
 
-  However, if the joystick is switch based (eg. clicks when you move it),
+However, if the joystick is switch based (eg. clicks when you move it),
 you might or might not, depending on your parallel port, need 10 kOhm pullup
-resistors on each of the direction and button signals, like this:
+resistors on each of the direction and button signals, like this::
 
-(pin 2) ------------+------> Up
-	  Resistor  |
-(pin 1) --[10kOhm]--+
+    (pin 2) ------------+------> Up
+              Resistor  |
+    (pin 1) --[10kOhm]--+
 
-  Try without, and if it doesn't work, add them. For TTL based joysticks /
+Try without, and if it doesn't work, add them. For TTL based joysticks /
 gamepads the pullups are not needed.
 
-  For joysticks with two buttons you connect the second button to pin 7 on
-the parallel port.
+For joysticks with two buttons you connect the second button to pin 7 on
+the parallel port::
 
-(pin 7) -----> Button 2
+    (pin 7) -----> Button 2
 
-  And that's it.
+And that's it.
 
-  On a side note, if you have already built a different adapter for use with
+On a side note, if you have already built a different adapter for use with
 the digital joystick driver 0.8.0.2, this is also supported by the db9.c
 driver, as device type 8. (See section 3.2)
 
-2.2.2 Multisystem joysticks using gamecon.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  For some people just one joystick per parallel port is not enough, and/or
+Multisystem joysticks using gamecon.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For some people just one joystick per parallel port is not enough, and/or
 want to use them on one parallel port together with NES/SNES/PSX pads. This is
 possible using the gamecon.c. It supports up to 5 devices of the above types,
 including 1 and 2 buttons Multisystem joysticks.
 
-  However, there is nothing for free. To allow more sticks to be used at
+However, there is nothing for free. To allow more sticks to be used at
 once, you need the sticks to be purely switch based (that is non-TTL), and
 not to need power. Just a plain simple six switches inside. If your
 joystick can do more (eg. turbofire) you'll need to disable it totally first
 if you want to use gamecon.c.
 
-  Also, the connection is a bit more complex. You'll need a bunch of diodes,
+Also, the connection is a bit more complex. You'll need a bunch of diodes,
 and one pullup resistor. First, you connect the Directions and the button
-the same as for db9, however with the diodes between.
+the same as for db9, however with the diodes between::
 
-	    Diodes
-(pin 2) -----|<|----> Up
-(pin 3) -----|<|----> Down
-(pin 4) -----|<|----> Left
-(pin 5) -----|<|----> Right
-(pin 6) -----|<|----> Button 1
+                Diodes
+    (pin 2) -----|<|----> Up
+    (pin 3) -----|<|----> Down
+    (pin 4) -----|<|----> Left
+    (pin 5) -----|<|----> Right
+    (pin 6) -----|<|----> Button 1
 
-  For two button sticks you also connect the other button.
+For two button sticks you also connect the other button::
 
-(pin 7) -----|<|----> Button 2
+    (pin 7) -----|<|----> Button 2
 
-  And finally, you connect the Ground wire of the joystick, like done in
+And finally, you connect the Ground wire of the joystick, like done in
 this little schematic to Power and Data on the parallel port, as described
 for the NES / SNES pads in section 2.1 of this file - that is, one data pin
-for each joystick. The power source is shared.
+for each joystick. The power source is shared::
 
-Data    ------------+-----> Ground
-	  Resistor  |
-Power   --[10kOhm]--+
+    Data    ------------+-----> Ground
+              Resistor  |
+    Power   --[10kOhm]--+
 
-  And that's all, here we go!
+And that's all, here we go!
 
-2.2.3 Multisystem joysticks using turbografx.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The TurboGraFX interface, designed by
+Multisystem joysticks using turbografx.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The TurboGraFX interface, designed by
 
 	Steffen Schwenke <schwenke@burg-halle.de>
 
-  allows up to 7 Multisystem joysticks connected to the parallel port. In
+allows up to 7 Multisystem joysticks connected to the parallel port. In
 Steffen's version, there is support for up to 5 buttons per joystick.  However,
 since this doesn't work reliably on all parallel ports, the turbografx.c driver
 supports only one button per joystick. For more information on how to build the
-interface, see
+interface, see:
 
 	http://www2.burg-halle.de/~schwenke/parport.html
 
-2.3 Sony Playstation
-~~~~~~~~~~~~~~~~~~~~
+Sony Playstation
+----------------
 
-  The PSX controller is supported by the gamecon.c. Pinout of the PSX
-controller (compatible with DirectPadPro):
+The PSX controller is supported by the gamecon.c. Pinout of the PSX
+controller (compatible with DirectPadPro)::
 
-  +---------+---------+---------+
-9 | o  o  o | o  o  o | o  o  o | 1               parallel
-   \________|_________|________/                  port pins
-    |  |      |  |  |   |
-    |  |      |  |  |   +-------->  Clock    ---  (4)
-    |  |      |  |  +------------>  Select   ---  (3)
-    |  |      |  +--------------->  Power    ---  (5-9)
-    |  |      +------------------>  Ground   ---  (18-25)
-    |  +------------------------->  Command  ---  (2)
-    +---------------------------->  Data     ---  (one of 10,11,12,13,15)
+    +---------+---------+---------+
+  9 | o  o  o | o  o  o | o  o  o | 1               parallel
+     \________|_________|________/                  port pins
+      |  |      |  |  |   |
+      |  |      |  |  |   +-------->  Clock    ---  (4)
+      |  |      |  |  +------------>  Select   ---  (3)
+      |  |      |  +--------------->  Power    ---  (5-9)
+      |  |      +------------------>  Ground   ---  (18-25)
+      |  +------------------------->  Command  ---  (2)
+      +---------------------------->  Data     ---  (one of 10,11,12,13,15)
 
-  The driver supports these controllers:
+The driver supports these controllers:
 
  * Standard PSX Pad
  * NegCon PSX Pad
@@ -336,207 +352,223 @@ controller (compatible with DirectPadPro):
  * PSX Rumble Pad
  * PSX DDR Pad
 
-2.4 Sega
-~~~~~~~~
-  All the Sega controllers are more or less based on the standard 2-button
+Sega
+----
+
+All the Sega controllers are more or less based on the standard 2-button
 Multisystem joystick. However, since they don't use switches and use TTL
 logic, the only driver usable with them is the db9.c driver.
 
-2.4.1 Sega Master System
-~~~~~~~~~~~~~~~~~~~~~~~~
-  The SMS gamepads are almost exactly the same as normal 2-button
+Sega Master System
+~~~~~~~~~~~~~~~~~~
+
+The SMS gamepads are almost exactly the same as normal 2-button
 Multisystem joysticks. Set the driver to Multi2 mode, use the corresponding
-parallel port pins, and the following schematic:
+parallel port pins, and the following schematic::
 
-    +-----------> Power
-    | +---------> Right
-    | | +-------> Left
-    | | | +-----> Down
-    | | | | +---> Up
-    | | | | |
-  _____________
-5 \ o o o o o / 1
-   \ o o x o /
-  9 `~~~~~~~' 6
-     | |   |
-     | |   +----> Button 1
-     | +--------> Ground
-     +----------> Button 2
+      +-----------> Power
+      | +---------> Right
+      | | +-------> Left
+      | | | +-----> Down
+      | | | | +---> Up
+      | | | | |
+    _____________
+  5 \ o o o o o / 1
+     \ o o x o /
+    9 `~~~~~~~' 6
+       | |   |
+       | |   +----> Button 1
+       | +--------> Ground
+       +----------> Button 2
 
-2.4.2 Sega Genesis aka MegaDrive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The Sega Genesis (in Europe sold as Sega MegaDrive) pads are an extension
+Sega Genesis aka MegaDrive
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Sega Genesis (in Europe sold as Sega MegaDrive) pads are an extension
 to the Sega Master System pads. They use more buttons (3+1, 5+1, 6+1).  Use
-the following schematic:
+the following schematic::
 
-    +-----------> Power
-    | +---------> Right
-    | | +-------> Left
-    | | | +-----> Down
-    | | | | +---> Up
-    | | | | |
-  _____________
-5 \ o o o o o / 1
-   \ o o o o /
-  9 `~~~~~~~' 6
-     | | | |
-     | | | +----> Button 1
-     | | +------> Select
-     | +--------> Ground
-     +----------> Button 2
+        +-----------> Power
+        | +---------> Right
+        | | +-------> Left
+        | | | +-----> Down
+        | | | | +---> Up
+        | | | | |
+      _____________
+    5 \ o o o o o / 1
+       \ o o o o /
+      9 `~~~~~~~' 6
+        | | | |
+        | | | +----> Button 1
+        | | +------> Select
+        | +--------> Ground
+        +----------> Button 2
 
-  The Select pin goes to pin 14 on the parallel port.
+The Select pin goes to pin 14 on the parallel port::
 
-(pin 14) -----> Select
+    (pin 14) -----> Select
 
-  The rest is the same as for Multi2 joysticks using db9.c
+The rest is the same as for Multi2 joysticks using db9.c
 
-2.4.3 Sega Saturn
-~~~~~~~~~~~~~~~~~
-  Sega Saturn has eight buttons, and to transfer that, without hacks like
+Sega Saturn
+~~~~~~~~~~~
+
+Sega Saturn has eight buttons, and to transfer that, without hacks like
 Genesis 6 pads use, it needs one more select pin. Anyway, it is still
 handled by the db9.c driver. Its pinout is very different from anything
-else.  Use this schematic:
+else.  Use this schematic::
 
-    +-----------> Select 1
-    | +---------> Power
-    | | +-------> Up
-    | | | +-----> Down
-    | | | | +---> Ground
-    | | | | |
-  _____________
-5 \ o o o o o / 1
-   \ o o o o /
-  9 `~~~~~~~' 6
-     | | | |
-     | | | +----> Select 2
-     | | +------> Right
-     | +--------> Left
-     +----------> Power
+      +-----------> Select 1
+      | +---------> Power
+      | | +-------> Up
+      | | | +-----> Down
+      | | | | +---> Ground
+      | | | | |
+    _____________
+  5 \ o o o o o / 1
+     \ o o o o /
+    9 `~~~~~~~' 6
+       | | | |
+       | | | +----> Select 2
+       | | +------> Right
+       | +--------> Left
+       +----------> Power
 
-  Select 1 is pin 14 on the parallel port, Select 2 is pin 16 on the
-parallel port.
+Select 1 is pin 14 on the parallel port, Select 2 is pin 16 on the
+parallel port::
 
-(pin 14) -----> Select 1
-(pin 16) -----> Select 2
+    (pin 14) -----> Select 1
+    (pin 16) -----> Select 2
 
-  The other pins (Up, Down, Right, Left, Power, Ground) are the same as for
+The other pins (Up, Down, Right, Left, Power, Ground) are the same as for
 Multi joysticks using db9.c
 
-3. The drivers
-~~~~~~~~~~~~~~
-  There are three drivers for the parallel port interfaces. Each, as
+The drivers
+===========
+
+There are three drivers for the parallel port interfaces. Each, as
 described above, allows to connect a different group of joysticks and pads.
 Here are described their command lines:
 
-3.1 gamecon.c
-~~~~~~~~~~~~~
-  Using gamecon.c you can connect up to five devices to one parallel port. It
-uses the following kernel/module command line:
+gamecon.c
+---------
+
+Using gamecon.c you can connect up to five devices to one parallel port. It
+uses the following kernel/module command line::
 
 	gamecon.map=port,pad1,pad2,pad3,pad4,pad5
 
-  Where 'port' the number of the parport interface (eg. 0 for parport0).
+Where ``port`` the number of the parport interface (eg. 0 for parport0).
 
-  And 'pad1' to 'pad5' are pad types connected to different data input pins
+And ``pad1`` to ``pad5`` are pad types connected to different data input pins
 (10,11,12,13,15), as described in section 2.1 of this file.
 
-  The types are:
+The types are:
 
-	Type | Joystick/Pad
-	--------------------
-	  0  | None
-	  1  | SNES pad
-	  2  | NES pad
-	  4  | Multisystem 1-button joystick
-	  5  | Multisystem 2-button joystick
-	  6  | N64 pad
-	  7  | Sony PSX controller
-	  8  | Sony PSX DDR controller
-	  9  | SNES mouse
+	===== =============================
+	Type  Joystick/Pad
+	===== =============================
+	  0   None
+	  1   SNES pad
+	  2   NES pad
+	  4   Multisystem 1-button joystick
+	  5   Multisystem 2-button joystick
+	  6   N64 pad
+	  7   Sony PSX controller
+	  8   Sony PSX DDR controller
+	  9   SNES mouse
+	===== =============================
 
-  The exact type of the PSX controller type is autoprobed when used, so
+The exact type of the PSX controller type is autoprobed when used, so
 hot swapping should work (but is not recommended).
 
-  Should you want to use more than one of parallel ports at once, you can use
+Should you want to use more than one of parallel ports at once, you can use
 gamecon.map2 and gamecon.map3 as additional command line parameters for two
 more parallel ports.
 
-  There are two options specific to PSX driver portion.  gamecon.psx_delay sets
+There are two options specific to PSX driver portion.  gamecon.psx_delay sets
 the command delay when talking to the controllers. The default of 25 should
 work but you can try lowering it for better performance. If your pads don't
 respond try raising it until they work. Setting the type to 8 allows the
 driver to be used with Dance Dance Revolution or similar games. Arrow keys are
 registered as key presses instead of X and Y axes.
 
-3.2 db9.c
-~~~~~~~~~
-  Apart from making an interface, there is nothing difficult on using the
-db9.c driver. It uses the following kernel/module command line:
+db9.c
+-----
+
+Apart from making an interface, there is nothing difficult on using the
+db9.c driver. It uses the following kernel/module command line::
 
 	db9.dev=port,type
 
-  Where 'port' is the number of the parport interface (eg. 0 for parport0).
+Where ``port`` is the number of the parport interface (eg. 0 for parport0).
 
-  Caveat here: This driver only works on bidirectional parallel ports. If
+Caveat here: This driver only works on bidirectional parallel ports. If
 your parallel port is recent enough, you should have no trouble with this.
 Old parallel ports may not have this feature.
 
-  'Type' is the type of joystick or pad attached:
+``Type`` is the type of joystick or pad attached:
 
-	Type | Joystick/Pad
-	--------------------
-	  0  | None
-	  1  | Multisystem 1-button joystick
-	  2  | Multisystem 2-button joystick
-	  3  | Genesis pad (3+1 buttons)
-	  5  | Genesis pad (5+1 buttons)
-	  6  | Genesis pad (6+2 buttons)
-	  7  | Saturn pad (8 buttons)
-	  8  | Multisystem 1-button joystick (v0.8.0.2 pin-out)
-	  9  | Two Multisystem 1-button joysticks (v0.8.0.2 pin-out) 
-	 10  | Amiga CD32 pad
+	===== ======================================================
+	Type  Joystick/Pad
+	===== ======================================================
+	  0   None
+	  1   Multisystem 1-button joystick
+	  2   Multisystem 2-button joystick
+	  3   Genesis pad (3+1 buttons)
+	  5   Genesis pad (5+1 buttons)
+	  6   Genesis pad (6+2 buttons)
+	  7   Saturn pad (8 buttons)
+	  8   Multisystem 1-button joystick (v0.8.0.2 pin-out)
+	  9   Two Multisystem 1-button joysticks (v0.8.0.2 pin-out)
+	 10   Amiga CD32 pad
+	===== ======================================================
 
-  Should you want to use more than one of these joysticks/pads at once, you
+Should you want to use more than one of these joysticks/pads at once, you
 can use db9.dev2 and db9.dev3 as additional command line parameters for two
 more joysticks/pads.
 
-3.3 turbografx.c
-~~~~~~~~~~~~~~~~
-  The turbografx.c driver uses a very simple kernel/module command line:
+turbografx.c
+------------
+
+The turbografx.c driver uses a very simple kernel/module command line::
 
 	turbografx.map=port,js1,js2,js3,js4,js5,js6,js7
 
-  Where 'port' is the number of the parport interface (eg. 0 for parport0).
+Where ``port`` is the number of the parport interface (eg. 0 for parport0).
 
-  'jsX' is the number of buttons the Multisystem joysticks connected to the
+``jsX`` is the number of buttons the Multisystem joysticks connected to the
 interface ports 1-7 have. For a standard multisystem joystick, this is 1.
 
-  Should you want to use more than one of these interfaces at once, you can
+Should you want to use more than one of these interfaces at once, you can
 use turbografx.map2 and turbografx.map3 as additional command line parameters
 for two more interfaces.
 
-3.4 PC parallel port pinout
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+PC parallel port pinout
+-----------------------
+
+::
+
 		  .----------------------------------------.
    At the PC:     \ 13 12 11 10  9  8  7  6  5  4  3  2  1 /
                    \  25 24 23 22 21 20 19 18 17 16 15 14 /
                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-	  Pin | Name    | Description
-	~~~~~~|~~~~~~~~~|~~~~~~~~~~
-	    1 | /STROBE | Strobe
-	  2-9 | D0-D7   | Data Bit 0-7
-	   10 | /ACK    | Acknowledge
-	   11 | BUSY    | Busy
-	   12 | PE      | Paper End
-	   13 | SELIN   | Select In
-	   14 | /AUTOFD | Autofeed
-	   15 | /ERROR  | Error
-	   16 | /INIT   | Initialize
-	   17 | /SEL    | Select
-	18-25 | GND     | Signal Ground
+======  =======  =============
+   Pin  Name     Description
+======  =======  =============
+     1  /STROBE  Strobe
+   2-9  D0-D7    Data Bit 0-7
+    10  /ACK     Acknowledge
+    11  BUSY     Busy
+    12  PE       Paper End
+    13  SELIN    Select In
+    14  /AUTOFD  Autofeed
+    15  /ERROR   Error
+    16  /INIT    Initialize
+    17  /SEL     Select
+ 18-25  GND      Signal Ground
+======  =======  =============
 
-3.5 End
-~~~~~~~
-  That's all, folks! Have fun!
+
+That's all, folks! Have fun!
-- 
2.9.3

[PATCH v2 22/33] docs: input/notifier: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/notifier.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/input/notifier.txt b/Documentation/input/notifier.txt
index 95172ca6f3d2..161350cb865e 100644
--- a/Documentation/input/notifier.txt
+++ b/Documentation/input/notifier.txt
@@ -1,4 +1,6 @@
+=================
 Keyboard notifier
+=================
 
 One can use register_keyboard_notifier to get called back on keyboard
 events (see kbd_keycode() function for details).  The passed structure is
@@ -23,9 +25,9 @@ For each kind of event but the last, the callback may return NOTIFY_STOP in
 order to "eat" the event: the notify loop is stopped and the keyboard event is
 dropped.
 
-In a rough C snippet, we have:
+In a rough C snippet, we have::
 
-kbd_keycode(keycode) {
+    kbd_keycode(keycode) {
 	...
 	params.value = keycode;
 	if (notifier_call_chain(KBD_KEYCODE,&params) == NOTIFY_STOP)
@@ -47,6 +49,6 @@ kbd_keycode(keycode) {
 		return;
 	apply keysym;
 	notifier_call_chain(KBD_POST_KEYSYM,&params);
-}
+    }
 
-NOTE: This notifier is usually called from interrupt context.
+.. note:: This notifier is usually called from interrupt context.
-- 
2.9.3

[PATCH v2 25/33] docs: input/sentelic: convert it to ReST format

[Mauro Carvalho Chehab]

This file has its own particular format that doesn't match any
markup one.

Manually change it to get something that would be readable
using ReST markup language.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/sentelic.txt | 1000 ++++++++++++++++++++------------------
 1 file changed, 514 insertions(+), 486 deletions(-)

diff --git a/Documentation/input/sentelic.txt b/Documentation/input/sentelic.txt
index 89251e2a3eba..d1a476f973b1 100644
--- a/Documentation/input/sentelic.txt
+++ b/Documentation/input/sentelic.txt
@@ -1,411 +1,437 @@
-Copyright (C) 2002-2011 Sentelic Corporation.
-Last update: Dec-07-2011
+.. include:: <isonum.txt>
+
+===============
+Sentelic Driver
+===============
+
+
+:Copyright: |copy| 2002-2011 Sentelic Corporation.
+
+:Last update: Dec-07-2011
+
+Finger Sensing Pad Intellimouse Mode(scrolling wheel, 4th and 5th buttons)
+==========================================================================
 
-==============================================================================
-* Finger Sensing Pad Intellimouse Mode(scrolling wheel, 4th and 5th buttons)
-==============================================================================
 A) MSID 4: Scrolling wheel mode plus Forward page(4th button) and Backward
    page (5th button)
-@1. Set sample rate to 200;
-@2. Set sample rate to 200;
-@3. Set sample rate to 80;
-@4. Issuing the "Get device ID" command (0xF2) and waits for the response;
-@5. FSP will respond 0x04.
-
-Packet 1
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |Y|X|y|x|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 | | |B|F|W|W|W|W|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7 => Y overflow
-        Bit6 => X overflow
-        Bit5 => Y sign bit
-        Bit4 => X sign bit
-        Bit3 => 1
-        Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X Movement(9-bit 2's complement integers)
-Byte 3: Y Movement(9-bit 2's complement integers)
-Byte 4: Bit3~Bit0 => the scrolling wheel's movement since the last data report.
-                     valid values, -8 ~ +7
-        Bit4 => 1 = 4th mouse button is pressed, Forward one page.
-                0 = 4th mouse button is not pressed.
-        Bit5 => 1 = 5th mouse button is pressed, Backward one page.
-                0 = 5th mouse button is not pressed.
-
-B) MSID 6: Horizontal and Vertical scrolling.
-@ Set bit 1 in register 0x40 to 1
-
-# FSP replaces scrolling wheel's movement as 4 bits to show horizontal and
-  vertical scrolling.
-
-Packet 1
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |Y|X|y|x|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 | | |B|F|r|l|u|d|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7 => Y overflow
-        Bit6 => X overflow
-        Bit5 => Y sign bit
-        Bit4 => X sign bit
-        Bit3 => 1
-        Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X Movement(9-bit 2's complement integers)
-Byte 3: Y Movement(9-bit 2's complement integers)
-Byte 4: Bit0 => the Vertical scrolling movement downward.
-	Bit1 => the Vertical scrolling movement upward.
-	Bit2 => the Horizontal scrolling movement leftward.
-	Bit3 => the Horizontal scrolling movement rightward.
-        Bit4 => 1 = 4th mouse button is pressed, Forward one page.
-                0 = 4th mouse button is not pressed.
-        Bit5 => 1 = 5th mouse button is pressed, Backward one page.
-                0 = 5th mouse button is not pressed.
-
-C) MSID 7:
-# FSP uses 2 packets (8 Bytes) to represent Absolute Position.
-  so we have PACKET NUMBER to identify packets.
+
+1. Set sample rate to 200;
+2. Set sample rate to 200;
+3. Set sample rate to 80;
+4. Issuing the "Get device ID" command (0xF2) and waits for the response;
+5. FSP will respond 0x04.
+
+::
+
+    Packet 1
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |Y|X|y|x|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 | | |B|F|W|W|W|W|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7 => Y overflow
+	    Bit6 => X overflow
+	    Bit5 => Y sign bit
+	    Bit4 => X sign bit
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X Movement(9-bit 2's complement integers)
+    Byte 3: Y Movement(9-bit 2's complement integers)
+    Byte 4: Bit3~Bit0 => the scrolling wheel's movement since the last data report.
+			valid values, -8 ~ +7
+	    Bit4 => 1 = 4th mouse button is pressed, Forward one page.
+		    0 = 4th mouse button is not pressed.
+	    Bit5 => 1 = 5th mouse button is pressed, Backward one page.
+		    0 = 5th mouse button is not pressed.
+
+B) MSID 6: Horizontal and Vertical scrolling
+
+- Set bit 1 in register 0x40 to 1
+
+FSP replaces scrolling wheel's movement as 4 bits to show horizontal and
+vertical scrolling.
+
+::
+
+    Packet 1
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |Y|X|y|x|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 | | |B|F|r|l|u|d|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7 => Y overflow
+	    Bit6 => X overflow
+	    Bit5 => Y sign bit
+	    Bit4 => X sign bit
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X Movement(9-bit 2's complement integers)
+    Byte 3: Y Movement(9-bit 2's complement integers)
+    Byte 4: Bit0 => the Vertical scrolling movement downward.
+	    Bit1 => the Vertical scrolling movement upward.
+	    Bit2 => the Horizontal scrolling movement leftward.
+	    Bit3 => the Horizontal scrolling movement rightward.
+	    Bit4 => 1 = 4th mouse button is pressed, Forward one page.
+		    0 = 4th mouse button is not pressed.
+	    Bit5 => 1 = 5th mouse button is pressed, Backward one page.
+		    0 = 5th mouse button is not pressed.
+
+C) MSID 7
+
+FSP uses 2 packets (8 Bytes) to represent Absolute Position.
+so we have PACKET NUMBER to identify packets.
+
   If PACKET NUMBER is 0, the packet is Packet 1.
   If PACKET NUMBER is 1, the packet is Packet 2.
   Please count this number in program.
 
-# MSID6 special packet will be enable at the same time when enable MSID 7.
-
-==============================================================================
-* Absolute position for STL3886-G0.
-==============================================================================
-@ Set bit 2 or 3 in register 0x40 to 1
-@ Set bit 6 in register 0x40 to 1
-
-Packet 1 (ABSOLUTE POSITION)
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|V|1|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|d|u|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordination packet
-                  => 10, Notify packet
-        Bit5 => valid bit
-        Bit4 => 1
-        Bit3 => 1
-        Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-        Bit3~Bit2 => X coordinate (ypos[1:0])
-        Bit4 => scroll up
-        Bit5 => scroll down
-        Bit6 => scroll left
-        Bit7 => scroll right
-
-Notify Packet for G0
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |1|0|0|1|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |M|M|M|M|M|M|M|M|  4 |0|0|0|0|0|0|0|0|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordination packet
-                  => 10, Notify packet
-        Bit5 => 0
-        Bit4 => 1
-        Bit3 => 1
-        Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: Message Type => 0x5A (Enable/Disable status packet)
-        Mode Type => 0xA5 (Normal/Icon mode status)
-Byte 3: Message Type => 0x00 (Disabled)
-                     => 0x01 (Enabled)
-        Mode Type    => 0x00 (Normal)
-                     => 0x01 (Icon)
-Byte 4: Bit7~Bit0 => Don't Care
-
-==============================================================================
-* Absolute position for STL3888-Ax.
-==============================================================================
-Packet 1 (ABSOLUTE POSITION)
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|V|A|1|L|0|1|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |x|x|y|y|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordination packet
-                  => 10, Notify packet
-                  => 11, Normal data packet with on-pad click
-        Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
-                When both fingers are up, the last two reports have zero valid
-                bit.
-        Bit4 => arc
-        Bit3 => 1
-        Bit2 => Left Button, 1 is pressed, 0 is released.
-        Bit1 => 0
-        Bit0 => 1
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-        Bit3~Bit2 => X coordinate (ypos[1:0])
-        Bit5~Bit4 => y1_g
-        Bit7~Bit6 => x1_g
-
-Packet 2 (ABSOLUTE POSITION)
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|V|A|1|R|1|0|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |x|x|y|y|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordinates packet
-                  => 10, Notify packet
-                  => 11, Normal data packet with on-pad click
-        Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
-                When both fingers are up, the last two reports have zero valid
-                bit.
-        Bit4 => arc
-        Bit3 => 1
-        Bit2 => Right Button, 1 is pressed, 0 is released.
-        Bit1 => 1
-        Bit0 => 0
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-        Bit3~Bit2 => X coordinate (ypos[1:0])
-        Bit5~Bit4 => y2_g
-        Bit7~Bit6 => x2_g
-
-Notify Packet for STL3888-Ax
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |1|0|1|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|d|u|0|0|0|0|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordinates packet
-                  => 10, Notify packet
-                  => 11, Normal data packet with on-pad click
-        Bit5 => 1
-        Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1):
-                0: left button is generated by the on-pad command
-                1: left button is generated by the external button
-        Bit3 => 1
-        Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode)
-Byte 3: Bit7~Bit6 => Don't care
-        Bit5~Bit4 => Number of fingers
-        Bit3~Bit1 => Reserved
-        Bit0 => 1: enter gesture mode; 0: leaving gesture mode
-Byte 4: Bit7 => scroll right button
-        Bit6 => scroll left button
-        Bit5 => scroll down button
-        Bit4 => scroll up button
-            * Note that if gesture and additional button (Bit4~Bit7)
-              happen at the same time, the button information will not
-              be sent.
-        Bit3~Bit0 => Reserved
+MSID6 special packet will be enable at the same time when enable MSID 7.
+
+Absolute position for STL3886-G0
+================================
+
+1. Set bit 2 or 3 in register 0x40 to 1
+2. Set bit 6 in register 0x40 to 1
+
+::
+
+    Packet 1 (ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|1|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|d|u|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordination packet
+		    => 10, Notify packet
+	    Bit5 => valid bit
+	    Bit4 => 1
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit4 => scroll up
+	    Bit5 => scroll down
+	    Bit6 => scroll left
+	    Bit7 => scroll right
+
+    Notify Packet for G0
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |1|0|0|1|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |M|M|M|M|M|M|M|M|  4 |0|0|0|0|0|0|0|0|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordination packet
+		    => 10, Notify packet
+	    Bit5 => 0
+	    Bit4 => 1
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: Message Type => 0x5A (Enable/Disable status packet)
+	    Mode Type => 0xA5 (Normal/Icon mode status)
+    Byte 3: Message Type => 0x00 (Disabled)
+			=> 0x01 (Enabled)
+	    Mode Type    => 0x00 (Normal)
+			=> 0x01 (Icon)
+    Byte 4: Bit7~Bit0 => Don't Care
+
+Absolute position for STL3888-Ax
+================================
+
+::
+
+    Packet 1 (ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|A|1|L|0|1|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |x|x|y|y|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordination packet
+		    => 10, Notify packet
+		    => 11, Normal data packet with on-pad click
+	    Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
+		    When both fingers are up, the last two reports have zero valid
+		    bit.
+	    Bit4 => arc
+	    Bit3 => 1
+	    Bit2 => Left Button, 1 is pressed, 0 is released.
+	    Bit1 => 0
+	    Bit0 => 1
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit5~Bit4 => y1_g
+	    Bit7~Bit6 => x1_g
+
+    Packet 2 (ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|A|1|R|1|0|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |x|x|y|y|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordinates packet
+		    => 10, Notify packet
+		    => 11, Normal data packet with on-pad click
+	    Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
+		    When both fingers are up, the last two reports have zero valid
+		    bit.
+	    Bit4 => arc
+	    Bit3 => 1
+	    Bit2 => Right Button, 1 is pressed, 0 is released.
+	    Bit1 => 1
+	    Bit0 => 0
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit5~Bit4 => y2_g
+	    Bit7~Bit6 => x2_g
+
+    Notify Packet for STL3888-Ax
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |1|0|1|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|d|u|0|0|0|0|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordinates packet
+		    => 10, Notify packet
+		    => 11, Normal data packet with on-pad click
+	    Bit5 => 1
+	    Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1):
+		    0: left button is generated by the on-pad command
+		    1: left button is generated by the external button
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode)
+    Byte 3: Bit7~Bit6 => Don't care
+	    Bit5~Bit4 => Number of fingers
+	    Bit3~Bit1 => Reserved
+	    Bit0 => 1: enter gesture mode; 0: leaving gesture mode
+    Byte 4: Bit7 => scroll right button
+	    Bit6 => scroll left button
+	    Bit5 => scroll down button
+	    Bit4 => scroll up button
+		* Note that if gesture and additional button (Bit4~Bit7)
+		happen at the same time, the button information will not
+		be sent.
+	    Bit3~Bit0 => Reserved
 
 Sample sequence of Multi-finger, Multi-coordinate mode:
 
 	notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1,
 	abs pkt 2, ..., notify packet (valid bit == 0)
 
-==============================================================================
-* Absolute position for STL3888-B0.
-==============================================================================
-Packet 1(ABSOLUTE POSITION)
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|V|F|1|0|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|u|d|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordinates packet
-                  => 10, Notify packet
-                  => 11, Normal data packet with on-pad click
-        Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
-                When both fingers are up, the last two reports have zero valid
-                bit.
-        Bit4 => finger up/down information. 1: finger down, 0: finger up.
-        Bit3 => 1
-        Bit2 => finger index, 0 is the first finger, 1 is the second finger.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-        Bit3~Bit2 => X coordinate (ypos[1:0])
-        Bit4 => scroll down button
-        Bit5 => scroll up button
-        Bit6 => scroll left button
-        Bit7 => scroll right button
-
-Packet 2 (ABSOLUTE POSITION)
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|V|F|1|1|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|u|d|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordination packet
-                  => 10, Notify packet
-                  => 11, Normal data packet with on-pad click
-        Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
-                When both fingers are up, the last two reports have zero valid
-                bit.
-        Bit4 => finger up/down information. 1: finger down, 0: finger up.
-        Bit3 => 1
-        Bit2 => finger index, 0 is the first finger, 1 is the second finger.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-        Bit3~Bit2 => X coordinate (ypos[1:0])
-        Bit4 => scroll down button
-        Bit5 => scroll up button
-        Bit6 => scroll left button
-        Bit7 => scroll right button
-
-Notify Packet for STL3888-B0
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |1|0|1|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|u|d|0|0|0|0|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordination packet
-                  => 10, Notify packet
-                  => 11, Normal data packet with on-pad click
-        Bit5 => 1
-        Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1):
-                0: left button is generated by the on-pad command
-                1: left button is generated by the external button
-        Bit3 => 1
-        Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode)
-Byte 3: Bit7~Bit6 => Don't care
-        Bit5~Bit4 => Number of fingers
-        Bit3~Bit1 => Reserved
-        Bit0 => 1: enter gesture mode; 0: leaving gesture mode
-Byte 4: Bit7 => scroll right button
-        Bit6 => scroll left button
-        Bit5 => scroll up button
-        Bit4 => scroll down button
-            * Note that if gesture and additional button(Bit4~Bit7)
-              happen at the same time, the button information will not
-              be sent.
-        Bit3~Bit0 => Reserved
+Absolute position for STL3888-B0
+================================
+
+::
+
+    Packet 1(ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|F|1|0|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|u|d|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordinates packet
+		    => 10, Notify packet
+		    => 11, Normal data packet with on-pad click
+	    Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
+		    When both fingers are up, the last two reports have zero valid
+		    bit.
+	    Bit4 => finger up/down information. 1: finger down, 0: finger up.
+	    Bit3 => 1
+	    Bit2 => finger index, 0 is the first finger, 1 is the second finger.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit4 => scroll down button
+	    Bit5 => scroll up button
+	    Bit6 => scroll left button
+	    Bit7 => scroll right button
+
+    Packet 2 (ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|F|1|1|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|u|d|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordination packet
+		    => 10, Notify packet
+		    => 11, Normal data packet with on-pad click
+	    Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
+		    When both fingers are up, the last two reports have zero valid
+		    bit.
+	    Bit4 => finger up/down information. 1: finger down, 0: finger up.
+	    Bit3 => 1
+	    Bit2 => finger index, 0 is the first finger, 1 is the second finger.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit4 => scroll down button
+	    Bit5 => scroll up button
+	    Bit6 => scroll left button
+	    Bit7 => scroll right button
+
+Notify Packet for STL3888-B0::
+
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |1|0|1|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|u|d|0|0|0|0|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordination packet
+		    => 10, Notify packet
+		    => 11, Normal data packet with on-pad click
+	    Bit5 => 1
+	    Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1):
+		    0: left button is generated by the on-pad command
+		    1: left button is generated by the external button
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode)
+    Byte 3: Bit7~Bit6 => Don't care
+	    Bit5~Bit4 => Number of fingers
+	    Bit3~Bit1 => Reserved
+	    Bit0 => 1: enter gesture mode; 0: leaving gesture mode
+    Byte 4: Bit7 => scroll right button
+	    Bit6 => scroll left button
+	    Bit5 => scroll up button
+	    Bit4 => scroll down button
+		* Note that if gesture and additional button(Bit4~Bit7)
+		happen at the same time, the button information will not
+		be sent.
+	    Bit3~Bit0 => Reserved
 
 Sample sequence of Multi-finger, Multi-coordinate mode:
 
 	notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1,
 	abs pkt 2, ..., notify packet (valid bit == 0)
 
-==============================================================================
-* Absolute position for STL3888-Cx and STL3888-Dx.
-==============================================================================
-Single Finger, Absolute Coordinate Mode (SFAC)
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|0|P|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|B|F|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordinates packet
-                  => 10, Notify packet
-	Bit5 => Coordinate mode(always 0 in SFAC mode):
-		0: single-finger absolute coordinates (SFAC) mode
-		1: multi-finger, multiple coordinates (MFMC) mode
-	Bit4 => 0: The LEFT button is generated by on-pad command (OPC)
-		1: The LEFT button is generated by external button
-		Default is 1 even if the LEFT button is not pressed.
-	Bit3 => Always 1, as specified by PS/2 protocol.
-	Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-	Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-	Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-	Bit3~Bit2 => X coordinate (ypos[1:0])
-	Bit4 => 4th mouse button(forward one page)
-	Bit5 => 5th mouse button(backward one page)
-	Bit6 => scroll left button
-	Bit7 => scroll right button
-
-Multi Finger, Multiple Coordinates Mode (MFMC):
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|1|P|1|F|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|B|F|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordination packet
-                  => 10, Notify packet
-	Bit5 => Coordinate mode (always 1 in MFMC mode):
-		0: single-finger absolute coordinates (SFAC) mode
-		1: multi-finger, multiple coordinates (MFMC) mode
-	Bit4 => 0: The LEFT button is generated by on-pad command (OPC)
-		1: The LEFT button is generated by external button
-		Default is 1 even if the LEFT button is not pressed.
-	Bit3 => Always 1, as specified by PS/2 protocol.
-	Bit2 => Finger index, 0 is the first finger, 1 is the second finger.
-		If bit 1 and 0 are all 1 and bit 4 is 0, the middle external
-		button is pressed.
-	Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-	Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-	Bit3~Bit2 => X coordinate (ypos[1:0])
-	Bit4 => 4th mouse button(forward one page)
-	Bit5 => 5th mouse button(backward one page)
-	Bit6 => scroll left button
-	Bit7 => scroll right button
-
-  When one of the two fingers is up, the device will output four consecutive
+Absolute position for STL3888-Cx and STL3888-Dx
+===============================================
+
+::
+
+    Single Finger, Absolute Coordinate Mode (SFAC)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|0|P|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|B|F|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordinates packet
+		    => 10, Notify packet
+	    Bit5 => Coordinate mode(always 0 in SFAC mode):
+		    0: single-finger absolute coordinates (SFAC) mode
+		    1: multi-finger, multiple coordinates (MFMC) mode
+	    Bit4 => 0: The LEFT button is generated by on-pad command (OPC)
+		    1: The LEFT button is generated by external button
+		    Default is 1 even if the LEFT button is not pressed.
+	    Bit3 => Always 1, as specified by PS/2 protocol.
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit4 => 4th mouse button(forward one page)
+	    Bit5 => 5th mouse button(backward one page)
+	    Bit6 => scroll left button
+	    Bit7 => scroll right button
+
+    Multi Finger, Multiple Coordinates Mode (MFMC):
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|1|P|1|F|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|B|F|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordination packet
+		    => 10, Notify packet
+	    Bit5 => Coordinate mode (always 1 in MFMC mode):
+		    0: single-finger absolute coordinates (SFAC) mode
+		    1: multi-finger, multiple coordinates (MFMC) mode
+	    Bit4 => 0: The LEFT button is generated by on-pad command (OPC)
+		    1: The LEFT button is generated by external button
+		    Default is 1 even if the LEFT button is not pressed.
+	    Bit3 => Always 1, as specified by PS/2 protocol.
+	    Bit2 => Finger index, 0 is the first finger, 1 is the second finger.
+		    If bit 1 and 0 are all 1 and bit 4 is 0, the middle external
+		    button is pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit4 => 4th mouse button(forward one page)
+	    Bit5 => 5th mouse button(backward one page)
+	    Bit6 => scroll left button
+	    Bit7 => scroll right button
+
+When one of the two fingers is up, the device will output four consecutive
 MFMC#0 report packets with zero X and Y to represent 1st finger is up or
 four consecutive MFMC#1 report packets with zero X and Y to represent that
 the 2nd finger is up.  On the other hand, if both fingers are up, the device
 will output four consecutive single-finger, absolute coordinate(SFAC) packets
 with zero X and Y.
 
-Notify Packet for STL3888-Cx/Dx
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |1|0|0|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|u|d|0|0|0|0|
-      |---------------|     |---------------|    |---------------|    |---------------|
+Notify Packet for STL3888-Cx/Dx::
 
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordinates packet
-                  => 10, Notify packet
-	Bit5 => Always 0
-	Bit4 => 0: The LEFT button is generated by on-pad command(OPC)
-		1: The LEFT button is generated by external button
-		Default is 1 even if the LEFT button is not pressed.
-	Bit3 => 1
-	Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-	Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-	Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: Message type:
-	0xba => gesture information
-	0xc0 => one finger hold-rotating gesture
-Byte 3: The first parameter for the received message:
-	0xba => gesture ID (refer to the 'Gesture ID' section)
-	0xc0 => region ID
-Byte 4: The second parameter for the received message:
-	0xba => N/A
-	0xc0 => finger up/down information
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |1|0|0|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|u|d|0|0|0|0|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordinates packet
+		    => 10, Notify packet
+	    Bit5 => Always 0
+	    Bit4 => 0: The LEFT button is generated by on-pad command(OPC)
+		    1: The LEFT button is generated by external button
+		    Default is 1 even if the LEFT button is not pressed.
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: Message type:
+	    0xba => gesture information
+	    0xc0 => one finger hold-rotating gesture
+    Byte 3: The first parameter for the received message:
+	    0xba => gesture ID (refer to the 'Gesture ID' section)
+	    0xc0 => region ID
+    Byte 4: The second parameter for the received message:
+	    0xba => N/A
+	    0xc0 => finger up/down information
 
 Sample sequence of Multi-finger, Multi-coordinates mode:
 
@@ -416,50 +442,51 @@ Sample sequence of Multi-finger, Multi-coordinates mode:
 	That is, when the device is in MFMC mode, the host will receive
 	interleaved absolute coordinate packets for each finger.
 
-==============================================================================
-* FSP Enable/Disable packet
-==============================================================================
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |Y|X|0|0|1|M|R|L|  2  |0|1|0|1|1|0|1|E|  3 | | | | | | | | |  4 | | | | | | | | |
-      |---------------|     |---------------|    |---------------|    |---------------|
+FSP Enable/Disable packet
+=========================
 
-FSP will send out enable/disable packet when FSP receive PS/2 enable/disable
-command. Host will receive the packet which Middle, Right, Left button will
-be set. The packet only use byte 0 and byte 1 as a pattern of original packet.
-Ignore the other bytes of the packet.
+::
 
-Byte 1: Bit7 => 0, Y overflow
-        Bit6 => 0, X overflow
-	Bit5 => 0, Y sign bit
-        Bit4 => 0, X sign bit
-	Bit3 => 1
-	Bit2 => 1, Middle Button
-        Bit1 => 1, Right Button
-        Bit0 => 1, Left Button
-Byte 2: Bit7~1 => (0101101b)
-        Bit0 => 1 = Enable
-		0 = Disable
-Byte 3: Don't care
-Byte 4: Don't care (MOUSE ID 3, 4)
-Byte 5~8: Don't care (Absolute packet)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |Y|X|0|0|1|M|R|L|  2  |0|1|0|1|1|0|1|E|  3 | | | | | | | | |  4 | | | | | | | | |
+	  |---------------|     |---------------|    |---------------|    |---------------|
 
-==============================================================================
-* PS/2 Command Set
-==============================================================================
+    FSP will send out enable/disable packet when FSP receive PS/2 enable/disable
+    command. Host will receive the packet which Middle, Right, Left button will
+    be set. The packet only use byte 0 and byte 1 as a pattern of original packet.
+    Ignore the other bytes of the packet.
+
+    Byte 1: Bit7 => 0, Y overflow
+	    Bit6 => 0, X overflow
+	    Bit5 => 0, Y sign bit
+	    Bit4 => 0, X sign bit
+	    Bit3 => 1
+	    Bit2 => 1, Middle Button
+	    Bit1 => 1, Right Button
+	    Bit0 => 1, Left Button
+    Byte 2: Bit7~1 => (0101101b)
+	    Bit0 => 1 = Enable
+		    0 = Disable
+    Byte 3: Don't care
+    Byte 4: Don't care (MOUSE ID 3, 4)
+    Byte 5~8: Don't care (Absolute packet)
+
+PS/2 Command Set
+================
 
 FSP supports basic PS/2 commanding set and modes, refer to following URL for
 details about PS/2 commands:
 
 http://www.computer-engineering.org/ps2mouse/
 
-==============================================================================
-* Programming Sequence for Determining Packet Parsing Flow
-==============================================================================
+Programming Sequence for Determining Packet Parsing Flow
+========================================================
+
 1. Identify FSP by reading device ID(0x00) and version(0x01) register
 
-2a. For FSP version < STL3888 Cx, determine number of buttons by reading
-    the 'test mode status' (0x20) register:
+2. For FSP version < STL3888 Cx, determine number of buttons by reading
+   the 'test mode status' (0x20) register::
 
 	buttons = reg[0x20] & 0x30
 
@@ -476,25 +503,24 @@ http://www.computer-engineering.org/ps2mouse/
 		Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse'
 		section A for packet parsing detail
 
-2b. For FSP version >= STL3888 Cx:
+3. For FSP version >= STL3888 Cx:
 	Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse'
 	section A for packet parsing detail (ignore byte 4, bit ~ 7)
 
-==============================================================================
-* Programming Sequence for Register Reading/Writing
-==============================================================================
+Programming Sequence for Register Reading/Writing
+=================================================
 
 Register inversion requirement:
 
-  Following values needed to be inverted(the '~' operator in C) before being
-sent to FSP:
+Following values needed to be inverted(the '~' operator in C) before being
+sent to FSP::
 
 	0xe8, 0xe9, 0xee, 0xf2, 0xf3 and 0xff.
 
 Register swapping requirement:
 
-  Following values needed to have their higher 4 bits and lower 4 bits being
-swapped before being sent to FSP:
+Following values needed to have their higher 4 bits and lower 4 bits being
+swapped before being sent to FSP::
 
 	10, 20, 40, 60, 80, 100 and 200.
 
@@ -512,33 +538,33 @@ Register reading sequence:
 	inverted(refer to the 'Register inversion requirement' section),
 	goto step 6
 
-	5a. send 0x68 PS/2 command to FSP;
+	  a. send 0x68 PS/2 command to FSP;
 
-	5b. send the inverted register address to FSP and goto step 8;
+	  b. send the inverted register address to FSP and goto step 8;
 
 	6. if the register address being to read is not required to be
 	swapped(refer to the 'Register swapping requirement' section),
 	goto step 7
 
-	6a. send 0xcc PS/2 command to FSP;
+	  a. send 0xcc PS/2 command to FSP;
 
-	6b. send the swapped register address to FSP and goto step 8;
+	  b. send the swapped register address to FSP and goto step 8;
 
 	7. send 0x66 PS/2 command to FSP;
 
-	7a. send the original register address to FSP and goto step 8;
+	  a. send the original register address to FSP and goto step 8;
 
 	8. send 0xe9(status request) PS/2 command to FSP;
 
 	9. the 4th byte of the response read from FSP should be the
-	requested register value(?? indicates don't care byte):
+	requested register value(?? indicates don't care byte)::
 
 		host: 0xe9
 		3888: 0xfa (??) (??) (val)
 
 	* Note that since the Cx release, the hardware will return 1's
-	complement of the register value at the 3rd byte of status request
-	result:
+	  complement of the register value at the 3rd byte of status request
+	  result::
 
 		host: 0xe9
 		3888: 0xfa (??) (~val) (val)
@@ -551,21 +577,21 @@ Register writing sequence:
 	inverted(refer to the 'Register inversion requirement' section),
 	goto step 3
 
-	2a. send 0x74 PS/2 command to FSP;
+	  a. send 0x74 PS/2 command to FSP;
 
-	2b. send the inverted register address to FSP and goto step 5;
+	  b. send the inverted register address to FSP and goto step 5;
 
 	3. if the register address being to write is not required to be
 	swapped(refer to the 'Register swapping requirement' section),
 	goto step 4
 
-	3a. send 0x77 PS/2 command to FSP;
+	  a. send 0x77 PS/2 command to FSP;
 
-	3b. send the swapped register address to FSP and goto step 5;
+	  b. send the swapped register address to FSP and goto step 5;
 
 	4. send 0x55 PS/2 command to FSP;
 
-	4a. send the register address to FSP and goto step 5;
+	  a. send the register address to FSP and goto step 5;
 
 	5. send 0xf3 PS/2 command to FSP;
 
@@ -573,43 +599,42 @@ Register writing sequence:
 	inverted(refer to the 'Register inversion requirement' section),
 	goto step 7
 
-	6a. send 0x47 PS/2 command to FSP;
+	  a. send 0x47 PS/2 command to FSP;
 
-	6b. send the inverted register value to FSP and goto step 9;
+	  b. send the inverted register value to FSP and goto step 9;
 
 	7. if the register value being to write is not required to be
 	swapped(refer to the 'Register swapping requirement' section),
 	goto step 8
 
-	7a. send 0x44 PS/2 command to FSP;
+	  a. send 0x44 PS/2 command to FSP;
 
-	7b. send the swapped register value to FSP and goto step 9;
+	  b. send the swapped register value to FSP and goto step 9;
 
 	8. send 0x33 PS/2 command to FSP;
 
-	8a. send the register value to FSP;
+	  a. send the register value to FSP;
 
 	9. the register writing sequence is completed.
 
-	* Note that since the Cx release, the hardware will return 1's
-	complement of the register value at the 3rd byte of status request
-	result. Host can optionally send another 0xe9 (status request) PS/2
-	command to FSP at the end of register writing to verify that the
-	register writing operation is successful (?? indicates don't care
-	byte):
+	* Since the Cx release, the hardware will return 1's
+	  complement of the register value at the 3rd byte of status request
+	  result. Host can optionally send another 0xe9 (status request) PS/2
+	  command to FSP at the end of register writing to verify that the
+	  register writing operation is successful (?? indicates don't care
+	  byte)::
 
 		host: 0xe9
 		3888: 0xfa (??) (~val) (val)
 
-==============================================================================
-* Programming Sequence for Page Register Reading/Writing
-==============================================================================
+Programming Sequence for Page Register Reading/Writing
+======================================================
 
-  In order to overcome the limitation of maximum number of registers
+In order to overcome the limitation of maximum number of registers
 supported, the hardware separates register into different groups called
 'pages.' Each page is able to include up to 255 registers.
 
-  The default page after power up is 0x82; therefore, if one has to get
+The default page after power up is 0x82; therefore, if one has to get
 access to register 0x8301, one has to use following sequence to switch
 to page 0x83, then start reading/writing from/to offset 0x01 by using
 the register read/write sequence described in previous section.
@@ -632,6 +657,7 @@ Page register reading sequence:
 
 	8. the response read from FSP should be the requested page value.
 
+
 Page register writing sequence:
 
 	1. send 0xf3 PS/2 command to FSP;
@@ -646,17 +672,17 @@ Page register writing sequence:
 	inverted(refer to the 'Register inversion requirement' section),
 	goto step 6
 
-	5a. send 0x47 PS/2 command to FSP;
+	  a. send 0x47 PS/2 command to FSP;
 
-	5b. send the inverted page address to FSP and goto step 9;
+	  b. send the inverted page address to FSP and goto step 9;
 
 	6. if the page address being written is not required to be
 	swapped(refer to the 'Register swapping requirement' section),
 	goto step 7
 
-	6a. send 0x44 PS/2 command to FSP;
+	  a. send 0x44 PS/2 command to FSP;
 
-	6b. send the swapped page address to FSP and goto step 9;
+	  b. send the swapped page address to FSP and goto step 9;
 
 	7. send 0x33 PS/2 command to FSP;
 
@@ -664,16 +690,17 @@ Page register writing sequence:
 
 	9. the page register writing sequence is completed.
 
-==============================================================================
-* Gesture ID
-==============================================================================
+Gesture ID
+==========
 
-  Unlike other devices which sends multiple fingers' coordinates to host,
+Unlike other devices which sends multiple fingers' coordinates to host,
 FSP processes multiple fingers' coordinates internally and convert them
 into a 8 bits integer, namely 'Gesture ID.'  Following is a list of
 supported gesture IDs:
 
+	======= ==================================
 	ID	Description
+	======= ==================================
 	0x86	2 finger straight up
 	0x82	2 finger straight down
 	0x80	2 finger straight right
@@ -687,38 +714,38 @@ supported gesture IDs:
 	0x28	3 finger straight right
 	0x2c	3 finger straight left
 	0x38	palm
+	======= ==================================
 
-==============================================================================
-* Register Listing
-==============================================================================
+Register Listing
+================
 
-  Registers are represented in 16 bits values. The higher 8 bits represent
+Registers are represented in 16 bits values. The higher 8 bits represent
 the page address and the lower 8 bits represent the relative offset within
 that particular page.  Refer to the 'Programming Sequence for Page Register
 Reading/Writing' section for instructions on how to change current page
-address.
+address::
 
-offset	width		default	r/w	name
-0x8200	bit7~bit0	0x01	RO	device ID
+ offset	width		default	r/w	name
+ 0x8200	bit7~bit0	0x01	RO	device ID
 
-0x8201	bit7~bit0		RW	version ID
+ 0x8201	bit7~bit0		RW	version ID
 					0xc1: STL3888 Ax
 					0xd0 ~ 0xd2: STL3888 Bx
 					0xe0 ~ 0xe1: STL3888 Cx
 					0xe2 ~ 0xe3: STL3888 Dx
 
-0x8202	bit7~bit0	0x01	RO	vendor ID
+ 0x8202	bit7~bit0	0x01	RO	vendor ID
 
-0x8203	bit7~bit0	0x01	RO	product ID
+ 0x8203	bit7~bit0	0x01	RO	product ID
 
-0x8204	bit3~bit0	0x01	RW	revision ID
+ 0x8204	bit3~bit0	0x01	RW	revision ID
 
-0x820b					test mode status 1
+ 0x820b					test mode status 1
 	bit3		1	RO	0: rotate 180 degree
 					1: no rotation
 					*only supported by H/W prior to Cx
 
-0x820f					register file page control
+ 0x820f					register file page control
 	bit2		0	RW	1: rotate 180 degree
 					0: no rotation
 					*supported since Cx
@@ -726,7 +753,7 @@ offset	width		default	r/w	name
 	bit0		0	RW	1 to enable page 1 register files
 					*only supported by H/W prior to Cx
 
-0x8210				RW	system control 1
+ 0x8210				RW	system control 1
 	bit0		1	RW	Reserved, must be 1
 	bit1		0	RW	Reserved, must be 0
 	bit4		0	RW	Reserved, must be 0
@@ -737,7 +764,7 @@ offset	width		default	r/w	name
 	40 41 42 43.  In addition to that, this bit must be 1 when gesture
 	mode is enabled)
 
-0x8220					test mode status
+ 0x8220					test mode status
 	bit5~bit4		RO	number of buttons
 					11 => 2, lbtn/rbtn
 					10 => 4, lbtn/rbtn/scru/scrd
@@ -745,13 +772,13 @@ offset	width		default	r/w	name
 					00 => 6, lbtn/rbtn/scru/scrd/fbtn/bbtn
 					*only supported by H/W prior to Cx
 
-0x8231				RW	on-pad command detection
+ 0x8231				RW	on-pad command detection
 	bit7		0	RW	on-pad command left button down tag
 					enable
 					0: disable, 1: enable
 					*only supported by H/W prior to Cx
 
-0x8234				RW	on-pad command control 5
+ 0x8234				RW	on-pad command control 5
 	bit4~bit0	0x05	RW	XLO in 0s/4/1, so 03h = 0010.1b = 2.5
 	(Note that position unit is in 0.5 scanline)
 					*only supported by H/W prior to Cx
@@ -760,22 +787,22 @@ offset	width		default	r/w	name
 					0: disable, 1: enable
 					*only supported by H/W prior to Cx
 
-0x8235				RW	on-pad command control 6
+ 0x8235				RW	on-pad command control 6
 	bit4~bit0	0x1d	RW	XHI in 0s/4/1, so 19h = 1100.1b = 12.5
 	(Note that position unit is in 0.5 scanline)
 					*only supported by H/W prior to Cx
 
-0x8236				RW	on-pad command control 7
+ 0x8236				RW	on-pad command control 7
 	bit4~bit0	0x04	RW	YLO in 0s/4/1, so 03h = 0010.1b = 2.5
 	(Note that position unit is in 0.5 scanline)
 					*only supported by H/W prior to Cx
 
-0x8237				RW	on-pad command control 8
+ 0x8237				RW	on-pad command control 8
 	bit4~bit0	0x13	RW	YHI in 0s/4/1, so 11h = 1000.1b = 8.5
 	(Note that position unit is in 0.5 scanline)
 					*only supported by H/W prior to Cx
 
-0x8240				RW	system control 5
+ 0x8240				RW	system control 5
 	bit1		0	RW	FSP Intellimouse mode enable
 					0: disable, 1: enable
 					*only supported by H/W prior to Cx
@@ -813,7 +840,7 @@ offset	width		default	r/w	name
 					0: disable, 1: enable
 					*only supported by H/W prior to Cx
 
-0x8243				RW	on-pad control
+ 0x8243				RW	on-pad control
 	bit0		0	RW	on-pad control enable
 					0: disable, 1: enable
 	(Note that if this bit is cleared, bit 3/5 will be ineffective)
@@ -827,7 +854,7 @@ offset	width		default	r/w	name
 					0: disable, 1: enable
 					*only supported by H/W prior to Cx
 
-0x8290				RW	software control register 1
+ 0x8290				RW	software control register 1
 	bit0		0	RW	absolute coordination mode
 					0: disable, 1: enable
 					*supported since Cx
@@ -856,16 +883,17 @@ offset	width		default	r/w	name
 					*supported since Cx
 
 	bit7		0	RW	Bx packet output compatible mode
-					0: disable, 1: enable					*supported since Cx
+					0: disable, 1: enable
+					*supported since Cx
 					*supported since Cx
 
 
-0x833d				RW	on-pad command control 1
+ 0x833d				RW	on-pad command control 1
 	bit7		1	RW	on-pad command detection enable
 					0: disable, 1: enable
 					*supported since Cx
 
-0x833e				RW	on-pad command detection
+ 0x833e				RW	on-pad command detection
 	bit7		0	RW	on-pad command left button down tag
 					enable. Works only in H/W based PS/2
 					data packet mode.
-- 
2.9.3

[PATCH v2 27/33] docs: input/walkera0701: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/walkera0701.txt | 53 +++++++++++++++++++++++++------------
 1 file changed, 36 insertions(+), 17 deletions(-)

diff --git a/Documentation/input/walkera0701.txt b/Documentation/input/walkera0701.txt
index 49e3ac60dcef..2adda99ca717 100644
--- a/Documentation/input/walkera0701.txt
+++ b/Documentation/input/walkera0701.txt
@@ -1,3 +1,6 @@
+===========================
+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:
-                   (ANALOG)
-    SYNC      BIN   OCT
-  +---------+      +------+
-  |         |      |      |
---+         +------+      +---
-
-Frame:
+Signal pulses
+-------------
+
+::
+
+                     (ANALOG)
+      SYNC      BIN   OCT
+    +---------+      +------+
+    |         |      |      |
+  --+         +------+      +---
+
+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.
-
-- 
2.9.3

[PATCH v2 30/33] docs-rst: create a book with Linux Input documentation

[Mauro Carvalho Chehab]

Now that all files under Documentation/input follows the
ReST markup language, rename them to *.rst and create a
book for the Linux Input subsystem.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/conf.py                              |  2 +
 Documentation/input/{alps.txt => alps.rst}         |  0
 Documentation/input/{amijoy.txt => amijoy.rst}     |  0
 .../input/{appletouch.txt => appletouch.rst}       |  0
 Documentation/input/{atarikbd.txt => atarikbd.rst} |  0
 Documentation/input/{bcm5974.txt => bcm5974.rst}   |  0
 Documentation/input/{cd32.txt => cd32.rst}         |  0
 .../input/{cma3000_d0x.txt => cma3000_d0x.rst}     |  0
 Documentation/input/conf.py                        | 10 +++
 Documentation/input/{cs461x.txt => cs461x.rst}     |  0
 .../input/{edt-ft5x06.txt => edt-ft5x06.rst}       |  0
 Documentation/input/{elantech.txt => elantech.rst} |  0
 .../input/{event-codes.txt => event-codes.rst}     |  0
 Documentation/input/{ff.txt => ff.rst}             |  0
 Documentation/input/{gamepad.txt => gamepad.rst}   |  0
 ...rt-programming.txt => gameport-programming.rst} |  0
 .../input/{gpio-tilt.txt => gpio-tilt.rst}         |  0
 .../{iforce-protocol.txt => iforce-protocol.rst}   |  0
 Documentation/input/index.rst                      | 77 ++++++++++++++++++++++
 ...input-programming.txt => input-programming.rst} |  0
 Documentation/input/{input.txt => input.rst}       | 20 ------
 .../input/{joystick-api.txt => joystick-api.rst}   |  0
 .../{joystick-parport.txt => joystick-parport.rst} |  0
 Documentation/input/{joystick.txt => joystick.rst} |  0
 ...touch-protocol.txt => multi-touch-protocol.rst} |  0
 Documentation/input/{notifier.txt => notifier.rst} |  0
 Documentation/input/{ntrig.txt => ntrig.rst}       |  0
 .../{rotary-encoder.txt => rotary-encoder.rst}     |  0
 Documentation/input/{sentelic.txt => sentelic.rst} |  0
 Documentation/input/{userio.txt => userio.rst}     |  0
 .../input/{walkera0701.txt => walkera0701.rst}     |  0
 Documentation/input/{xpad.txt => xpad.rst}         |  0
 Documentation/input/{yealink.txt => yealink.rst}   |  0
 33 files changed, 89 insertions(+), 20 deletions(-)
 rename Documentation/input/{alps.txt => alps.rst} (100%)
 rename Documentation/input/{amijoy.txt => amijoy.rst} (100%)
 rename Documentation/input/{appletouch.txt => appletouch.rst} (100%)
 rename Documentation/input/{atarikbd.txt => atarikbd.rst} (100%)
 rename Documentation/input/{bcm5974.txt => bcm5974.rst} (100%)
 rename Documentation/input/{cd32.txt => cd32.rst} (100%)
 rename Documentation/input/{cma3000_d0x.txt => cma3000_d0x.rst} (100%)
 create mode 100644 Documentation/input/conf.py
 rename Documentation/input/{cs461x.txt => cs461x.rst} (100%)
 rename Documentation/input/{edt-ft5x06.txt => edt-ft5x06.rst} (100%)
 rename Documentation/input/{elantech.txt => elantech.rst} (100%)
 rename Documentation/input/{event-codes.txt => event-codes.rst} (100%)
 rename Documentation/input/{ff.txt => ff.rst} (100%)
 rename Documentation/input/{gamepad.txt => gamepad.rst} (100%)
 rename Documentation/input/{gameport-programming.txt => gameport-programming.rst} (100%)
 rename Documentation/input/{gpio-tilt.txt => gpio-tilt.rst} (100%)
 rename Documentation/input/{iforce-protocol.txt => iforce-protocol.rst} (100%)
 create mode 100644 Documentation/input/index.rst
 rename Documentation/input/{input-programming.txt => input-programming.rst} (100%)
 rename Documentation/input/{input.txt => input.rst} (92%)
 rename Documentation/input/{joystick-api.txt => joystick-api.rst} (100%)
 rename Documentation/input/{joystick-parport.txt => joystick-parport.rst} (100%)
 rename Documentation/input/{joystick.txt => joystick.rst} (100%)
 rename Documentation/input/{multi-touch-protocol.txt => multi-touch-protocol.rst} (100%)
 rename Documentation/input/{notifier.txt => notifier.rst} (100%)
 rename Documentation/input/{ntrig.txt => ntrig.rst} (100%)
 rename Documentation/input/{rotary-encoder.txt => rotary-encoder.rst} (100%)
 rename Documentation/input/{sentelic.txt => sentelic.rst} (100%)
 rename Documentation/input/{userio.txt => userio.rst} (100%)
 rename Documentation/input/{walkera0701.txt => walkera0701.rst} (100%)
 rename Documentation/input/{xpad.txt => xpad.rst} (100%)
 rename Documentation/input/{yealink.txt => yealink.rst} (100%)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 7fadb3b83293..fef209edb4d7 100644
--- a/Documentation/conf.py
+++ b/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',
diff --git a/Documentation/input/alps.txt b/Documentation/input/alps.rst
similarity index 100%
rename from Documentation/input/alps.txt
rename to Documentation/input/alps.rst
diff --git a/Documentation/input/amijoy.txt b/Documentation/input/amijoy.rst
similarity index 100%
rename from Documentation/input/amijoy.txt
rename to Documentation/input/amijoy.rst
diff --git a/Documentation/input/appletouch.txt b/Documentation/input/appletouch.rst
similarity index 100%
rename from Documentation/input/appletouch.txt
rename to Documentation/input/appletouch.rst
diff --git a/Documentation/input/atarikbd.txt b/Documentation/input/atarikbd.rst
similarity index 100%
rename from Documentation/input/atarikbd.txt
rename to Documentation/input/atarikbd.rst
diff --git a/Documentation/input/bcm5974.txt b/Documentation/input/bcm5974.rst
similarity index 100%
rename from Documentation/input/bcm5974.txt
rename to Documentation/input/bcm5974.rst
diff --git a/Documentation/input/cd32.txt b/Documentation/input/cd32.rst
similarity index 100%
rename from Documentation/input/cd32.txt
rename to Documentation/input/cd32.rst
diff --git a/Documentation/input/cma3000_d0x.txt b/Documentation/input/cma3000_d0x.rst
similarity index 100%
rename from Documentation/input/cma3000_d0x.txt
rename to Documentation/input/cma3000_d0x.rst
diff --git a/Documentation/input/conf.py b/Documentation/input/conf.py
new file mode 100644
index 000000000000..d2352fdc92ed
--- /dev/null
+++ b/Documentation/input/conf.py
@@ -0,0 +1,10 @@
+# -*- 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'),
+]
diff --git a/Documentation/input/cs461x.txt b/Documentation/input/cs461x.rst
similarity index 100%
rename from Documentation/input/cs461x.txt
rename to Documentation/input/cs461x.rst
diff --git a/Documentation/input/edt-ft5x06.txt b/Documentation/input/edt-ft5x06.rst
similarity index 100%
rename from Documentation/input/edt-ft5x06.txt
rename to Documentation/input/edt-ft5x06.rst
diff --git a/Documentation/input/elantech.txt b/Documentation/input/elantech.rst
similarity index 100%
rename from Documentation/input/elantech.txt
rename to Documentation/input/elantech.rst
diff --git a/Documentation/input/event-codes.txt b/Documentation/input/event-codes.rst
similarity index 100%
rename from Documentation/input/event-codes.txt
rename to Documentation/input/event-codes.rst
diff --git a/Documentation/input/ff.txt b/Documentation/input/ff.rst
similarity index 100%
rename from Documentation/input/ff.txt
rename to Documentation/input/ff.rst
diff --git a/Documentation/input/gamepad.txt b/Documentation/input/gamepad.rst
similarity index 100%
rename from Documentation/input/gamepad.txt
rename to Documentation/input/gamepad.rst
diff --git a/Documentation/input/gameport-programming.txt b/Documentation/input/gameport-programming.rst
similarity index 100%
rename from Documentation/input/gameport-programming.txt
rename to Documentation/input/gameport-programming.rst
diff --git a/Documentation/input/gpio-tilt.txt b/Documentation/input/gpio-tilt.rst
similarity index 100%
rename from Documentation/input/gpio-tilt.txt
rename to Documentation/input/gpio-tilt.rst
diff --git a/Documentation/input/iforce-protocol.txt b/Documentation/input/iforce-protocol.rst
similarity index 100%
rename from Documentation/input/iforce-protocol.txt
rename to Documentation/input/iforce-protocol.rst
diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst
new file mode 100644
index 000000000000..153f0d476c3e
--- /dev/null
+++ b/Documentation/input/index.rst
@@ -0,0 +1,77 @@
+=============================
+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
+========
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   input
+   input-programming
+   event-codes
+   joystick
+   joystick-api
+   multi-touch-protocol
+   gamepad
+   gameport-programming
+   ff
+   notifier
+   userio
+
+Input drivers
+=============
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   alps
+   amijoy
+   appletouch
+   atarikbd
+   bcm5974
+   cd32
+   cma3000_d0x
+   cs461x
+   edt-ft5x06
+   elantech
+   iforce-protocol
+   joystick-parport
+   gpio-tilt
+   ntrig
+   rotary-encoder
+   sentelic
+   walkera0701
+   xpad
+   yealink
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/input/input-programming.txt b/Documentation/input/input-programming.rst
similarity index 100%
rename from Documentation/input/input-programming.txt
rename to Documentation/input/input-programming.rst
diff --git a/Documentation/input/input.txt b/Documentation/input/input.rst
similarity index 92%
rename from Documentation/input/input.txt
rename to Documentation/input/input.rst
index fda995e0ceb0..ac7669ad3e76 100644
--- a/Documentation/input/input.txt
+++ b/Documentation/input/input.rst
@@ -6,30 +6,10 @@ Linux Input drivers
 
 :Copyright: |copy| 1999-2001 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.
-
 Introduction
 ============
 
diff --git a/Documentation/input/joystick-api.txt b/Documentation/input/joystick-api.rst
similarity index 100%
rename from Documentation/input/joystick-api.txt
rename to Documentation/input/joystick-api.rst
diff --git a/Documentation/input/joystick-parport.txt b/Documentation/input/joystick-parport.rst
similarity index 100%
rename from Documentation/input/joystick-parport.txt
rename to Documentation/input/joystick-parport.rst
diff --git a/Documentation/input/joystick.txt b/Documentation/input/joystick.rst
similarity index 100%
rename from Documentation/input/joystick.txt
rename to Documentation/input/joystick.rst
diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.rst
similarity index 100%
rename from Documentation/input/multi-touch-protocol.txt
rename to Documentation/input/multi-touch-protocol.rst
diff --git a/Documentation/input/notifier.txt b/Documentation/input/notifier.rst
similarity index 100%
rename from Documentation/input/notifier.txt
rename to Documentation/input/notifier.rst
diff --git a/Documentation/input/ntrig.txt b/Documentation/input/ntrig.rst
similarity index 100%
rename from Documentation/input/ntrig.txt
rename to Documentation/input/ntrig.rst
diff --git a/Documentation/input/rotary-encoder.txt b/Documentation/input/rotary-encoder.rst
similarity index 100%
rename from Documentation/input/rotary-encoder.txt
rename to Documentation/input/rotary-encoder.rst
diff --git a/Documentation/input/sentelic.txt b/Documentation/input/sentelic.rst
similarity index 100%
rename from Documentation/input/sentelic.txt
rename to Documentation/input/sentelic.rst
diff --git a/Documentation/input/userio.txt b/Documentation/input/userio.rst
similarity index 100%
rename from Documentation/input/userio.txt
rename to Documentation/input/userio.rst
diff --git a/Documentation/input/walkera0701.txt b/Documentation/input/walkera0701.rst
similarity index 100%
rename from Documentation/input/walkera0701.txt
rename to Documentation/input/walkera0701.rst
diff --git a/Documentation/input/xpad.txt b/Documentation/input/xpad.rst
similarity index 100%
rename from Documentation/input/xpad.txt
rename to Documentation/input/xpad.rst
diff --git a/Documentation/input/yealink.txt b/Documentation/input/yealink.rst
similarity index 100%
rename from Documentation/input/yealink.txt
rename to Documentation/input/yealink.rst
-- 
2.9.3

[PATCH v2 32/33] docs: input/interactive: convert from xfig to svg

[Mauro Carvalho Chehab]

We're using svg as the standard format for vectorial images.

Convert it to .svg, in a way that it is easily editable.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/interactive.fig | 42 -------------------------------------
 Documentation/input/interactive.svg | 24 +++++++++++++++++++++
 2 files changed, 24 insertions(+), 42 deletions(-)
 delete mode 100644 Documentation/input/interactive.fig
 create mode 100644 Documentation/input/interactive.svg

diff --git a/Documentation/input/interactive.fig b/Documentation/input/interactive.fig
deleted file mode 100644
index 1e7de387723a..000000000000
--- a/Documentation/input/interactive.fig
+++ /dev/null
@@ -1,42 +0,0 @@
-#FIG 3.2
-Landscape
-Center
-Inches
-Letter  
-100.00
-Single
--2
-1200 2
-2 1 0 2 0 7 50 0 -1 6.000 0 0 -1 0 0 6
-	 1200 3600 1800 3600 2400 4800 3000 4800 4200 5700 4800 5700
-2 2 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 5
-	 1200 3150 4800 3150 4800 6300 1200 6300 1200 3150
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 1200 4800 4800 4800
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4
-	 2400 4800 2400 6525 1950 7125 1950 7800
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4
-	 3000 4800 3000 6525 3600 7125 3600 7800
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 1 3
-	0 0 1.00 60.00 120.00
-	 3825 5400 4125 5100 5400 5100
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 1 3
-	0 0 1.00 60.00 120.00
-	 2100 4200 2400 3900 5400 3900
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 4800 5700 5400 5700
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 1800 3600 5400 3600
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 1 3
-	0 0 1.00 60.00 120.00
-	 2700 4800 2700 4425 5400 4425
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2
-	0 0 1.00 60.00 120.00
-	0 0 1.00 60.00 120.00
-	 1950 7800 3600 7800
-4 1 0 50 0 0 12 0.0000 4 135 810 2775 7725 Dead band\001
-4 0 0 50 0 0 12 0.0000 4 180 1155 5400 5700 right saturation\001
-4 0 0 50 0 0 12 0.0000 4 135 1065 5400 3600 left saturation\001
-4 0 0 50 0 0 12 0.0000 4 180 2505 5400 3900 left coeff ( positive in that case )\001
-4 0 0 50 0 0 12 0.0000 4 180 2640 5475 5100 right coeff ( negative in that case )\001
-4 0 0 50 0 0 12 0.0000 4 105 480 5400 4425 center\001
diff --git a/Documentation/input/interactive.svg b/Documentation/input/interactive.svg
new file mode 100644
index 000000000000..a3513709a09b
--- /dev/null
+++ b/Documentation/input/interactive.svg
@@ -0,0 +1,24 @@
+<svg width="5.75in" height="3.90in" version="1.1" viewBox="1178 3138 6779.9424 4671.3427" xmlns="http://www.w3.org/2000/svg">
+ <polyline transform="translate(-18.5,-16.294)" points="1200 3600 1800 3600 2400 4800 3e3 4800 4200 5700 4800 5700" fill="none" stroke="#000" stroke-width="15"/>
+ <rect x="1181.5" y="3133.7" width="3600" height="3150" rx="0" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="1200 4800 4800 4800" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="2400 4800 2400 6525 1950 7125 1950 7800" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="3e3 4800 3e3 6525 3600 7125 3600 7800" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="3837 5389 4125 5100 5400 5100" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="3889 5292 3826 5398 3932 5334" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="2112 4189 2400 3900 5400 3900" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="2164 4092 2101 4198 2207 4134" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="4800 5700 5400 5700" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="1800 3600 5400 3600" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="2700 4784 2700 4425 5400 4425" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="2670 4678 2700 4798 2730 4678" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="1967 7800 3583 7800" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="3478 7830 3598 7800 3478 7770" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="2072 7770 1952 7800 2072 7830" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <text x="2775" y="7725" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" text-anchor="middle" xml:space="preserve">Dead band</text>
+ <text x="5400" y="5700" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">right saturation</text>
+ <text x="5400" y="3600" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">left saturation</text>
+ <text x="5400" y="3900" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">left coeff ( positive in that case )</text>
+ <text x="5475" y="5100" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">right coeff ( negative in that case )</text>
+ <text x="5400" y="4425" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">center</text>
+</svg>
-- 
2.9.3

[PATCH v2 01/37] docs: Documentation/input/input: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST.

Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/input.txt | 240 +++++++++++++++++++++++-------------------
 1 file changed, 131 insertions(+), 109 deletions(-)

diff --git a/Documentation/input/input.txt b/Documentation/input/input.txt
index 7ebce100fe90..fda995e0ceb0 100644
--- a/Documentation/input/input.txt
+++ b/Documentation/input/input.txt
@@ -1,59 +1,67 @@
-			  Linux Input drivers v1.0
-	       (c) 1999-2001 Vojtech Pavlik <vojtech@ucw.cz>
-			     Sponsored by SuSE
-----------------------------------------------------------------------------
-
-0. Disclaimer
-~~~~~~~~~~~~~
-  This program is free software; you can redistribute it and/or modify it
+.. include:: <isonum.txt>
+
+===================
+Linux Input drivers
+===================
+
+:Copyright: |copy| 1999-2001 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
+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
+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
+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
+For your convenience, the GNU General Public License version 2 is included
 in the package: See the file COPYING.
 
-1. Introduction
-~~~~~~~~~~~~~~~
-  This is a collection of drivers that is designed to support all input
+Introduction
+============
+
+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/.
 
-  The centre of the input drivers is the input module, which must be
+The centre of the input drivers 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:
 
-1.1 Device drivers
-~~~~~~~~~~~~~~~~~~
-  These modules talk to the hardware (for example via USB), and provide
+Device drivers
+--------------
+
+These modules talk to the hardware (for example via USB), and provide
 events (keystrokes, mouse movements) to the input module.
 
-1.2 Event handlers
-~~~~~~~~~~~~~~~~~~
-  These modules get events from input and pass them where needed via
+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.
 
-2. Simple Usage
-~~~~~~~~~~~~~~~
-  For the most usual configuration, with one USB mouse and one USB keyboard,
+Simple Usage
+============
+
+For the most usual configuration, with one USB mouse and one USB keyboard,
 you'll have to load the following modules (or have them built in to the
-kernel):
+kernel)::
 
 	input
 	mousedev
@@ -62,24 +70,25 @@ kernel):
 	uhci_hcd or ohci_hcd or ehci_hcd
 	usbhid
 
-  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:
+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 has to be created.
+
+The commands to create it by hand are::
 
 	cd /dev
 	mkdir input
 	mknod input/mice c 13 63
 
-  After that you have to point GPM (the textmode mouse cut&paste tool) and
-XFree to this device to use it - GPM should be called like:
+After that you have to point GPM (the textmode mouse cut&paste tool) and
+XFree to this device to use it - GPM should be called like::
 
 	gpm -t ps2 -m /dev/input/mice
 
-  And in X:
+And in X::
 
 	Section "Pointer"
 	    Protocol    "ImPS/2"
@@ -87,97 +96,107 @@ XFree to this device to use it - GPM should be called like:
 	    ZAxisMapping 4 5
 	EndSection
 
-  When you do all of the above, you can use your USB mouse and keyboard.
+When you do all of the above, you can use your USB mouse and keyboard.
 
-3. Detailed Description
-~~~~~~~~~~~~~~~~~~~~~~~
-3.1 Device drivers
-~~~~~~~~~~~~~~~~~~
-  Device drivers are the modules that generate events. The events are
+Detailed Description
+====================
+
+Device drivers
+--------------
+
+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.
 
-3.1.1 usbhid
-~~~~~~~~~~~~
-  usbhid is the largest and most complex driver of the whole suite. It
+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
+Currently, it handles USB mice, joysticks, gamepads, steering wheels
 keyboards, trackballs and digitizers.
 
- However, USB uses HID also for monitor controls, speaker controls, UPSs,
+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
+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,
+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
+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.
 
-3.1.2 usbmouse
-~~~~~~~~~~~~~~
-  For embedded systems, for mice with broken HID descriptors and just any
+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.
 
-3.1.3 usbkbd
-~~~~~~~~~~~~
-  Much like usbmouse, this module talks to keyboards with a simplified
+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.
 
-3.1.4 wacom
-~~~~~~~~~~~
-  This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom
+wacom
+~~~~~
+
+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.
 
-3.1.5 iforce
-~~~~~~~~~~~~
-  A driver for I-Force joysticks and wheels, both over USB and RS232. 
+iforce
+~~~~~~
+
+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. 
+about it.
 
-3.2 Event handlers
-~~~~~~~~~~~~~~~~~~
-  Event handlers distribute the events from the devices to userland and
+Event handlers
+--------------
+
+Event handlers distribute the events from the devices to userland and
 kernel, as needed.
 
-3.2.1 keybdev
-~~~~~~~~~~~~~
-  keybdev is currently a rather ugly hack that translates the input
+keybdev
+~~~~~~~
+
+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.
 
-  The right way would be to pass the events to keyboard.c directly,
+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. 
+the input patch, available on the webpage mentioned below.
 
-3.2.2 mousedev
-~~~~~~~~~~~~~~
-  mousedev is also a hack to make programs that use mouse input
+mousedev
+~~~~~~~~
+
+mousedev is also a hack to make 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
 
-  Mousedev devices in /dev/input (as shown above) are:
+Mousedev devices in /dev/input (as shown above) are::
 
 	crw-r--r--   1 root     root      13,  32 Mar 28 22:45 mouse0
 	crw-r--r--   1 root     root      13,  33 Mar 29 00:41 mouse1
@@ -188,31 +207,32 @@ for example evdev
 	crw-r--r--   1 root     root      13,  62 Apr  1 10:50 mouse30
 	crw-r--r--   1 root     root      13,  63 Apr  1 10:50 mice
 
-Each 'mouse' device is assigned to a single mouse or digitizer, except
-the last one - 'mice'. This single character device is shared by all
+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.
 
-  CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
+CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
 the size of your screen (in pixels) in XFree86. This is needed if you
 want to use your digitizer in X, because its movement is sent to X
 via a virtual PS/2 mouse and thus needs to be scaled
 accordingly. These values won't be used if you use a mouse only.
 
-  Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
+Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
 ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the
 program reading the data wishes. You can set GPM and X to any of
 these. You'll need ImPS/2 if you want to make use of a wheel on a USB
-mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons. 
+mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons.
 
-3.2.3 joydev
-~~~~~~~~~~~~
-  Joydev implements v0.x and v1.x Linux joystick api, much like
+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: 
+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
@@ -222,19 +242,20 @@ on:
 
 And so on up to js31.
 
-3.2.4 evdev
-~~~~~~~~~~~
-  evdev is the generic input event interface. It passes the events
+evdev
+~~~~~
+
+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. 
+section 5.
 
-  This should be the way for GPM and X to get keyboard and mouse
+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.
 
-  The devices are in /dev/input:
+The devices are in /dev/input::
 
 	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
@@ -244,47 +265,48 @@ are hardware independent.
 
 And so on up to event31.
 
-4. Verifying if it works
-~~~~~~~~~~~~~~~~~~~~~~~~
-  Typing a couple keys on the keyboard should be enough to check that
+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
-driver. 
+driver.
 
-  Doing a "cat /dev/input/mouse0" (c, 13, 32) will verify that a mouse
+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,
+You can test the joystick emulation with the ``jstest`` utility,
 available in the joystick package (see Documentation/input/joystick.txt).
 
-  You can test the event devices with the 'evtest' utility available
+You can test the event devices with the ``evtest`` utility available
 in the LinuxConsole project CVS archive (see the URL below).
 
-5. Event interface
-~~~~~~~~~~~~~~~~~~
-  Should you want to add event device support into any application (X, gpm,
+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, 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:
+events on a read. Their layout is::
 
-struct input_event {
-	struct timeval time;
-	unsigned short type;
-	unsigned short code;
-	unsigned int value;
-};
+    struct input_event {
+	    struct timeval time;
+	    unsigned short type;
+	    unsigned short code;
+	    unsigned int value;
+    };
 
-  'time' is the timestamp, it returns the time at which the event happened.
+``time`` is the timestamp, it returns the time at which the event happened.
 Type is for example EV_REL for relative moment, EV_KEY for a keypress or
 release. More types are defined in include/uapi/linux/input-event-codes.h.
 
-  'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete
+``code`` is event code, for example REL_X or KEY_BACKSPACE, again a complete
 list is in include/uapi/linux/input-event-codes.h.
 
-  'value' is the value the event carries. Either a relative change for
+``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.
-
-- 
2.9.3

[PATCH v2 02/37] docs: input/alps: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/alps.txt | 43 ++++++++++++++++++++++++++-----------------
 1 file changed, 26 insertions(+), 17 deletions(-)

diff --git a/Documentation/input/alps.txt b/Documentation/input/alps.txt
index 8d1341ccde64..76a71a146e50 100644
--- a/Documentation/input/alps.txt
+++ b/Documentation/input/alps.txt
@@ -1,3 +1,4 @@
+----------------------
 ALPS Touchpad Protocol
 ----------------------
 
@@ -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
-- 
2.9.3

[PATCH v2 03/37] docs: input/amijoy: convert it to ReST format

[Mauro Carvalho Chehab]

This file contains lots of tables, but none formatted using
the ReST syntax. Adjust them to match the ReST syntax
and add a title for the document.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/amijoy.txt | 165 +++++++++++++++++++++++++++++------------
 1 file changed, 118 insertions(+), 47 deletions(-)

diff --git a/Documentation/input/amijoy.txt b/Documentation/input/amijoy.txt
index 7dc4f175943c..25f516888a29 100644
--- a/Documentation/input/amijoy.txt
+++ b/Documentation/input/amijoy.txt
@@ -1,67 +1,100 @@
+~~~~~~~~~~~~~~~~~~~~~~~~~
+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 +104,16 @@ 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
@@ -88,12 +125,19 @@ 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)     |
          +--------+----------+-----------------------------------------+
 
@@ -106,44 +150,59 @@ 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,13 +214,18 @@ 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.
@@ -170,15 +234,22 @@ POTINP     016   R   Paula  Pot pin data read
          | 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) |
          +-------+----------+---------------------------------------------+
-
--------------------------------------------------------------------------------
-- 
2.9.3

[PATCH v2 04/37] docs: input/appletouch: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/appletouch.txt | 33 ++++++++++++++++++++-------------
 1 file changed, 20 insertions(+), 13 deletions(-)

diff --git a/Documentation/input/appletouch.txt b/Documentation/input/appletouch.txt
index b13de3f89108..d56bd383d99c 100644
--- a/Documentation/input/appletouch.txt
+++ b/Documentation/input/appletouch.txt
@@ -1,12 +1,17 @@
+.. 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.
@@ -27,13 +32,13 @@ 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"
-	        Driver          "synaptics"
+		Identifier      "Synaptics Touchpad"
+		Driver          "synaptics"
 		Option          "SendCoreEvents"        "true"
 		Option          "Device"                "/dev/input/mice"
 		Option          "Protocol"              "auto-dev"
@@ -73,13 +78,15 @@ 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
 	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>`_
-- 
2.9.3

[PATCH v2 05/37] docs: input/atarikbd: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

We opted to remove section numbers, as this can be automatically
generated on Sphinx, by using :numbered: tag at index.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/atarikbd.txt | 214 +++++++++++++++++++++++++++++----------
 1 file changed, 161 insertions(+), 53 deletions(-)

diff --git a/Documentation/input/atarikbd.txt b/Documentation/input/atarikbd.txt
index f3a3ba8847ba..032c065a031a 100644
--- a/Documentation/input/atarikbd.txt
+++ b/Documentation/input/atarikbd.txt
@@ -1,7 +1,10 @@
+====================================
 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,19 +32,23 @@ 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:
+
+=================== ====================================================
     0xF6            status report
     0xF7            absolute mouse position record
     0xF8-0xFB       relative mouse position records (lsbs determined by
-                     mouse button states)
+                    mouse button states)
     0xFC            time-of-day
     0xFD            joystick report (both sticks)
     0xFE            joystick 0 event
     0xFF            joystick 1 event
+=================== ====================================================
 
 The two shift keys return different scan codes in this mode. The ENTER key
 and the RETurn key are also distinct.
 
-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 +61,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 +76,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 +91,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 +111,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 +150,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 +161,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 +172,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 +206,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 +235,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
@@ -217,14 +247,17 @@ without being preceded by the make code is a flag for a key matrix error).
                         ;  position report
                         ;  where y=1, mouse key press causes absolute report
                         ;  and x=1, mouse key release causes absolute report
-                        ; mss=100, mouse buttons act like keys 
+                        ; mss=100, mouse buttons act like keys
 
 This command sets how the ikbd should treat the buttons on the mouse. The
 default mouse button action mode is %00000000, the buttons are treated as part
 of the mouse logically.
 When buttons act like keys, LEFT=0x74 & RIGHT=0x75.
 
-9.3 SET RELATIVE MOUSE POSITION REPORTING
+SET RELATIVE MOUSE POSITION REPORTING
+-------------------------------------
+
+::
 
     0x08
 
@@ -235,14 +268,17 @@ 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)
     XLSB
     YMSB                ; Y maximum (in scaled mouse clicks)
     YLSB
-	
+
 Set absolute mouse position maintenance. Resets the ikbd maintained X and Y
 coordinates.
 In this mode, the value of the internally maintained coordinates does NOT wrap
@@ -250,7 +286,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 +302,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 +316,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 +333,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 +354,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 +369,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 +381,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 +393,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 +405,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 +419,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 +447,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 +478,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 +497,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 +513,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 +546,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 +559,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 +577,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 +594,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 +608,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 +623,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,8 +635,11 @@ 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 +673,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,13 +700,15 @@ 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.
 
+======= ============
 Hex	Keytop
 01	Esc
 02	1
@@ -643,7 +750,7 @@ Hex	Keytop
 26	L
 27	;
 28	'
-29	`
+29	\`
 2A	(LEFT) SHIFT
 2B	\
 2C	Z
@@ -707,3 +814,4 @@ Hex	Keytop
 70	KEYPAD 0
 71	KEYPAD .
 72	KEYPAD ENTER
+======= ============
-- 
2.9.3

[PATCH v2 06/37] docs: input/bcm5974: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/bcm5974.txt | 43 +++++++++++++++++++++++------------------
 1 file changed, 24 insertions(+), 19 deletions(-)

diff --git a/Documentation/input/bcm5974.txt b/Documentation/input/bcm5974.txt
index 74d3876d6f34..4aca199b0aa6 100644
--- a/Documentation/input/bcm5974.txt
+++ b/Documentation/input/bcm5974.txt
@@ -1,19 +1,25 @@
+.. 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/
-- 
2.9.3

[PATCH v2 07/37] docs: input/cd32: convert it to ReST format

[Mauro Carvalho Chehab]

Currently, it misses a title, and the table is not valid for
ReST.

Adjust them, in order for it to be able to parse on Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/cd32.txt | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/Documentation/input/cd32.txt b/Documentation/input/cd32.txt
index a003d9b41eca..2bffe0f33e5e 100644
--- a/Documentation/input/cd32.txt
+++ b/Documentation/input/cd32.txt
@@ -1,3 +1,7 @@
+==========
+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
@@ -5,15 +9,15 @@ 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)
-
+===========    =============
+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)
+===========    =============
-- 
2.9.3

[PATCH v2 08/37] docs: input/cma3000_d0x: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/cma3000_d0x.txt | 72 ++++++++++++++++++++++++-------------
 1 file changed, 48 insertions(+), 24 deletions(-)

diff --git a/Documentation/input/cma3000_d0x.txt b/Documentation/input/cma3000_d0x.txt
index 29d088db4afd..6f40c17c1aca 100644
--- a/Documentation/input/cma3000_d0x.txt
+++ b/Documentation/input/cma3000_d0x.txt
@@ -1,30 +1,37 @@
 Kernel driver for CMA3000-D0x
-============================
+=============================
 
 Supported chips:
 * VTI CMA3000-D0x
+
 Datasheet:
   CMA3000-D0X Product Family Specification 8281000A.02.pdf
   <http://www.vti.fi/en/>
 
-Author: Hemanth V <hemanthv@ti.com>
+: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
 
-mdfftmr: Motion detect and free fall time threshold value
+mdthr:
+    Motion detect g range threshold value
 
-ffthr: Free fall g range threshold value
+mdfftmr:
+    Motion detect and free fall time threshold value
+
+ffthr:
+    Free fall g range threshold value
 
 Input Interface
---------------
+---------------
+
 Input driver version is 1.0.0
 Input device ID: bus 0x18 vendor 0x0 product 0x0 version 0x0
 Input device name: "cma3000-accelerometer"
-Supported events:
+
+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)
-- 
2.9.3

[PATCH v2 09/37] docs: input/cs461x: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/cs461x.txt | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/Documentation/input/cs461x.txt b/Documentation/input/cs461x.txt
index 202e9dbacec3..1450436dcc9e 100644
--- a/Documentation/input/cs461x.txt
+++ b/Documentation/input/cs461x.txt
@@ -1,36 +1,40 @@
-Preface.
+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 
+Crystal SoundFusion CS4610/CS4612/CS4615. This code is based upon
 Vortex/Solo drivers as an example of decoration style, and ALSA
 0.5.8a kernel drivers as an chipset documentation and samples.
 
-This version does not have cooked mode support; the basic code 
-is present here, but have not tested completely. The button analysis 
-is completed in this mode, but the axis movement is not. 
+This version does not have cooked mode support; the basic code
+is present here, but have not tested completely. The button analysis
+is completed in this mode, but the axis movement is not.
 
 Raw mode works fine with analog joystick front-end driver and cs461x
-driver as a backend. I've tested this driver with CS4610, 4-axis and 
+driver as a backend. I've tested this driver with CS4610, 4-axis and
 4-button joystick; I mean the jstest utility. Also I've tried to
 play in xracer game using joystick, and the result is better than
 keyboard only mode.
 
 The sensitivity and calibrate quality have not been tested; the two
-reasons are performed: the same hardware cannot work under Win95 (blue 
-screen in VJOYD); I have no documentation on my chip; and the existing 
-behavior in my case was not raised the requirement of joystick calibration. 
+reasons are performed: the same hardware cannot work under Win95 (blue
+screen in VJOYD); I have no documentation on my chip; and the existing
+behavior in my case was not raised the requirement of joystick calibration.
 So the driver have no code to perform hardware related calibration.
 
 The patch contains minor changes of Config.in and Makefile files. All
 needed code have been moved to one separate file cs461x.c like ns558.c
 This driver have the basic support for PCI devices only; there is no
-ISA or PnP ISA cards supported. AFAIK the ns558 have support for Crystal 
+ISA or PnP ISA cards supported. AFAIK the ns558 have support for Crystal
 ISA and PnP ISA series.
 
 The driver works with ALSA drivers simultaneously. For example, the xracer
 uses joystick as input device and PCM device as sound output in one time.
 There are no sound or input collisions detected. The source code have
-comments about them; but I've found the joystick can be initialized 
+comments about them; but I've found the joystick can be initialized
 separately of ALSA modules. So, you can use only one joystick driver
 without ALSA drivers. The ALSA drivers are not needed to compile or
 run this driver.
@@ -38,7 +42,7 @@ run this driver.
 There are no debug information print have been placed in source, and no
 specific options required to work this driver. The found chipset parameters
 are printed via printk(KERN_INFO "..."), see the /var/log/messages to
-inspect cs461x: prefixed messages to determine possible card detection 
+inspect cs461x: prefixed messages to determine possible card detection
 errors.
 
 Regards,
-- 
2.9.3

[PATCH v2 10/37] docs: input/elantech: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

We opted to remove section numbers, as this can be automatically
generated on Sphinx, by using :numbered: tag at index.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/elantech.txt | 306 +++++++++++++++++++++------------------
 1 file changed, 165 insertions(+), 141 deletions(-)

diff --git a/Documentation/input/elantech.txt b/Documentation/input/elantech.txt
index 1ec0db7879d3..bb1302246506 100644
--- a/Documentation/input/elantech.txt
+++ b/Documentation/input/elantech.txt
@@ -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::
 
-byte 3:
+   not used
+
+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
 
-- 
2.9.3

[PATCH v2 11/37] docs: input/event-codes: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
---
 Documentation/input/event-codes.txt | 132 +++++++++++++++++++++++++-----------
 1 file changed, 92 insertions(+), 40 deletions(-)

diff --git a/Documentation/input/event-codes.txt b/Documentation/input/event-codes.txt
index 36ea940e5bb9..92db50954169 100644
--- a/Documentation/input/event-codes.txt
+++ b/Documentation/input/event-codes.txt
@@ -1,3 +1,8 @@
+=================
+Input event codes
+=================
+
+
 The input protocol uses a map of types and codes to express input device values
 to userspace. This document describes the types and codes and how and when they
 may be used.
@@ -17,82 +22,102 @@ reports supported by a device are also provided by sysfs in
 class/input/event*/device/capabilities/, and the properties of a device are
 provided in class/input/event*/device/properties.
 
-Event types:
+Event types
 ===========
+
 Event types are groupings of codes under a logical input construct. Each
 type has a set of applicable codes to be used in generating events. See the
 Codes section for details on valid codes for each type.
 
 * EV_SYN:
+
   - Used as markers to separate events. Events may be separated in time or in
     space, such as with the multitouch protocol.
 
 * EV_KEY:
+
   - Used to describe state changes of keyboards, buttons, or other key-like
     devices.
 
 * EV_REL:
+
   - Used to describe relative axis value changes, e.g. moving the mouse 5 units
     to the left.
 
 * EV_ABS:
+
   - Used to describe absolute axis value changes, e.g. describing the
     coordinates of a touch on a touchscreen.
 
 * EV_MSC:
+
   - Used to describe miscellaneous input data that do not fit into other types.
 
 * EV_SW:
+
   - Used to describe binary state input switches.
 
 * EV_LED:
+
   - Used to turn LEDs on devices on and off.
 
 * EV_SND:
+
   - Used to output sound to devices.
 
 * EV_REP:
+
   - Used for autorepeating devices.
 
 * EV_FF:
+
   - Used to send force feedback commands to an input device.
 
 * EV_PWR:
+
   - A special type for power button and switch input.
 
 * EV_FF_STATUS:
+
   - Used to receive force feedback device status.
 
-Event codes:
+Event codes
 ===========
+
 Event codes define the precise type of event.
 
-EV_SYN:
-----------
+EV_SYN
+------
+
 EV_SYN event values are undefined. Their usage is defined only by when they are
 sent in the evdev event stream.
 
 * SYN_REPORT:
+
   - Used to synchronize and separate events into packets of input data changes
     occurring at the same moment in time. For example, motion of a mouse may set
     the REL_X and REL_Y values for one motion, then emit a SYN_REPORT. The next
     motion will emit more REL_X and REL_Y values and send another SYN_REPORT.
 
 * SYN_CONFIG:
+
   - TBD
 
 * SYN_MT_REPORT:
+
   - Used to synchronize and separate touch events. See the
     multi-touch-protocol.txt document for more information.
 
 * SYN_DROPPED:
+
   - Used to indicate buffer overrun in the evdev client's event queue.
     Client should ignore all events up to and including next SYN_REPORT
     event and query the device (using EVIOCG* ioctls) to obtain its
     current state.
 
-EV_KEY:
-----------
+EV_KEY
+------
+
 EV_KEY events take the form KEY_<name> or BTN_<name>. For example, KEY_A is used
 to represent the 'A' key on a keyboard. When a key is depressed, an event with
 the key's code is emitted with value 1. When the key is released, an event is
@@ -103,6 +128,7 @@ BTN_<name> is used for other types of momentary switch events.
 A few EV_KEY codes have special meanings:
 
 * BTN_TOOL_<name>:
+
   - These codes are used in conjunction with input trackpads, tablets, and
     touchscreens. These devices may be used with fingers, pens, or other tools.
     When an event occurs and a tool is used, the corresponding BTN_TOOL_<name>
@@ -112,6 +138,7 @@ A few EV_KEY codes have special meanings:
     code when events are generated.
 
 * BTN_TOUCH:
+
     BTN_TOUCH is used for touch contact. While an input tool is determined to be
     within meaningful physical contact, the value of this property must be set
     to 1. Meaningful physical contact may mean any contact, or it may mean
@@ -132,6 +159,7 @@ future, this distinction will be deprecated and the device properties ioctl
 EVIOCGPROP, defined in linux/input.h, will be used to convey the device type.
 
 * BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP, BTN_TOOL_TRIPLETAP, BTN_TOOL_QUADTAP:
+
   - These codes denote one, two, three, and four finger interaction on a
     trackpad or touchscreen. For example, if the user uses two fingers and moves
     them on the touchpad in an effort to scroll content on screen,
@@ -147,8 +175,9 @@ a value of 1 in the same synchronization frame. This usage is deprecated.
 Note: In multitouch drivers, the input_mt_report_finger_count() function should
 be used to emit these codes. Please see multi-touch-protocol.txt for details.
 
-EV_REL:
-----------
+EV_REL
+------
+
 EV_REL events describe relative changes in a property. For example, a mouse may
 move to the left by a certain number of units, but its absolute position in
 space is unknown. If the absolute position is known, EV_ABS codes should be used
@@ -157,17 +186,20 @@ instead of EV_REL codes.
 A few EV_REL codes have special meanings:
 
 * REL_WHEEL, REL_HWHEEL:
+
   - These codes are used for vertical and horizontal scroll wheels,
     respectively.
 
-EV_ABS:
-----------
+EV_ABS
+------
+
 EV_ABS events describe absolute changes in a property. For example, a touchpad
 may emit coordinates for a touch location.
 
 A few EV_ABS codes have special meanings:
 
 * ABS_DISTANCE:
+
   - Used to describe the distance of a tool from an interaction surface. This
     event should only be emitted while the tool is hovering, meaning in close
     proximity of the device and while the value of the BTN_TOUCH code is 0. If
@@ -179,11 +211,13 @@ A few EV_ABS codes have special meanings:
     hardware and is otherwise independent of ABS_DISTANCE and/or BTN_TOUCH.
 
 * ABS_MT_<name>:
+
   - Used to describe multitouch input events. Please see
     multi-touch-protocol.txt for details.
 
-EV_SW:
-----------
+EV_SW
+-----
+
 EV_SW events describe stateful binary switches. For example, the SW_LID code is
 used to denote when a laptop lid is closed.
 
@@ -195,14 +229,16 @@ Upon resume, if the switch state is the same as before suspend, then the input
 subsystem will filter out the duplicate switch state reports. The driver does
 not need to keep the state of the switch at any time.
 
-EV_MSC:
-----------
+EV_MSC
+------
+
 EV_MSC events are used for input and output events that do not fall under other
 categories.
 
 A few EV_MSC codes have special meaning:
 
 * MSC_TIMESTAMP:
+
   - Used to report the number of microseconds since the last reset. This event
     should be coded as an uint32 value, which is allowed to wrap around with
     no special consequence. It is assumed that the time difference between two
@@ -211,39 +247,46 @@ A few EV_MSC codes have special meaning:
     unknown.  If the device does not provide this information, the driver must
     not provide it to user space.
 
-EV_LED:
-----------
+EV_LED
+------
+
 EV_LED events are used for input and output to set and query the state of
 various LEDs on devices.
 
-EV_REP:
-----------
+EV_REP
+------
+
 EV_REP events are used for specifying autorepeating events.
 
-EV_SND:
-----------
+EV_SND
+------
+
 EV_SND events are used for sending sound commands to simple sound output
 devices.
 
-EV_FF:
-----------
+EV_FF
+-----
+
 EV_FF events are used to initialize a force feedback capable device and to cause
 such device to feedback.
 
-EV_PWR:
-----------
+EV_PWR
+------
+
 EV_PWR events are a special type of event used specifically for power
 management. Its usage is not well defined. To be addressed later.
 
-Device properties:
+Device properties
 =================
+
 Normally, userspace sets up an input device based on the data it emits,
 i.e., the event types. In the case of two devices emitting the same event
 types, additional information can be provided in the form of device
 properties.
 
-INPUT_PROP_DIRECT + INPUT_PROP_POINTER:
+INPUT_PROP_DIRECT + INPUT_PROP_POINTER
 --------------------------------------
+
 The INPUT_PROP_DIRECT property indicates that device coordinates should be
 directly mapped to screen coordinates (not taking into account trivial
 transformations, such as scaling, flipping and rotating). Non-direct input
@@ -260,8 +303,9 @@ If neither INPUT_PROP_DIRECT or INPUT_PROP_POINTER are set, the property is
 considered undefined and the device type should be deduced in the
 traditional way, using emitted event types.
 
-INPUT_PROP_BUTTONPAD:
+INPUT_PROP_BUTTONPAD
 --------------------
+
 For touchpads where the button is placed beneath the surface, such that
 pressing down on the pad causes a button click, this property should be
 set. Common in clickpad notebooks and macbooks from 2009 and onwards.
@@ -270,8 +314,9 @@ Originally, the buttonpad property was coded into the bcm5974 driver
 version field under the name integrated button. For backwards
 compatibility, both methods need to be checked in userspace.
 
-INPUT_PROP_SEMI_MT:
+INPUT_PROP_SEMI_MT
 ------------------
+
 Some touchpads, most common between 2008 and 2011, can detect the presence
 of multiple contacts without resolving the individual positions; only the
 number of contacts and a rectangular shape is known. For such
@@ -285,9 +330,10 @@ gestures can normally be extracted from it.
 If INPUT_PROP_SEMI_MT is not set, the device is assumed to be a true MT
 device.
 
-INPUT_PROP_TOPBUTTONPAD:
+INPUT_PROP_TOPBUTTONPAD
 -----------------------
-Some laptops, most notably the Lenovo *40 series provide a trackstick
+
+Some laptops, most notably the Lenovo 40 series provide a trackstick
 device but do not have physical buttons associated with the trackstick
 device. Instead, the top area of the touchpad is marked to show
 visual/haptic areas for left, middle, right buttons intended to be used
@@ -299,26 +345,30 @@ The kernel does not provide button emulation for such devices but treats
 them as any other INPUT_PROP_BUTTONPAD device.
 
 INPUT_PROP_ACCELEROMETER
--------------------------
+------------------------
+
 Directional axes on this device (absolute and/or relative x, y, z) represent
 accelerometer data. All other axes retain their meaning. A device must not mix
 regular directional axes and accelerometer axes on the same event node.
 
-Guidelines:
+Guidelines
 ==========
+
 The guidelines below ensure proper single-touch and multi-finger functionality.
 For multi-touch functionality, see the multi-touch-protocol.txt document for
 more information.
 
-Mice:
-----------
+Mice
+----
+
 REL_{X,Y} must be reported when the mouse moves. BTN_LEFT must be used to report
 the primary button press. BTN_{MIDDLE,RIGHT,4,5,etc.} should be used to report
 further buttons of the device. REL_WHEEL and REL_HWHEEL should be used to report
 scroll wheel events where available.
 
-Touchscreens:
-----------
+Touchscreens
+------------
+
 ABS_{X,Y} must be reported with the location of the touch. BTN_TOUCH must be
 used to report when a touch is active on the screen.
 BTN_{MOUSE,LEFT,MIDDLE,RIGHT} must not be reported as the result of touch
@@ -326,8 +376,9 @@ contact. BTN_TOOL_<name> events should be reported where possible.
 
 For new hardware, INPUT_PROP_DIRECT should be set.
 
-Trackpads:
-----------
+Trackpads
+---------
+
 Legacy trackpads that only provide relative position information must report
 events like mice described above.
 
@@ -338,8 +389,9 @@ be used to report the number of touches active on the trackpad.
 
 For new hardware, INPUT_PROP_POINTER should be set.
 
-Tablets:
-----------
+Tablets
+-------
+
 BTN_TOOL_<name> events must be reported when a stylus or other tool is active on
 the tablet. ABS_{X,Y} must be reported with the location of the tool. BTN_TOUCH
 should be used to report when the tool is in contact with the tablet.
-- 
2.9.3

[PATCH v2 12/37] docs: input/ff: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/ff.txt | 188 +++++++++++++++++++++++++++------------------
 1 file changed, 112 insertions(+), 76 deletions(-)

diff --git a/Documentation/input/ff.txt b/Documentation/input/ff.txt
index b3867bf49f8f..6d6688a63dd8 100644
--- a/Documentation/input/ff.txt
+++ b/Documentation/input/ff.txt
@@ -1,12 +1,16 @@
-Force feedback for Linux.
-By Johann Deneux <johann.deneux@gmail.com> on 2001/04/22.
-Updated by Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09.
+========================
+Force feedback for Linux
+========================
+
+:Author: Johann Deneux <johann.deneux@gmail.com> on 2001/04/22.
+:Updated: Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09.
+
 You may redistribute this file. Please remember to include shape.fig and
 interactive.fig as well.
-----------------------------------------------------------------------------
 
-1. Introduction
-~~~~~~~~~~~~~~~
+Introduction
+~~~~~~~~~~~~
+
 This document describes how to use force feedback devices under Linux. The
 goal is not to support these devices as if they were simple input-only devices
 (as it is already the case), but to really enable the rendering of force
@@ -15,8 +19,9 @@ This document only describes the force feedback part of the Linux input
 interface. Please read joystick.txt and input.txt before reading further this
 document.
 
-2. Instructions to the user
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Instructions to the user
+~~~~~~~~~~~~~~~~~~~~~~~~
+
 To enable force feedback, you have to:
 
 1. have your kernel configured with evdev and a driver that supports your
@@ -33,39 +38,48 @@ something goes wrong.
 If you have a serial iforce device, you need to start inputattach. See
 joystick.txt for details.
 
-2.1 Does it work ?
-~~~~~~~~~~~~~~~~~~
-There is an utility called fftest that will allow you to test the driver.
-% fftest /dev/input/eventXX
+Does it work ?
+--------------
+
+There is an utility called fftest that will allow you to test the driver::
+
+    % fftest /dev/input/eventXX
+
+Instructions to the developer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-3. Instructions to the developer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 All interactions are done using the event API. That is, you can use ioctl()
 and write() on /dev/input/eventXX.
 This information is subject to change.
 
-3.1 Querying device capabilities
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#include <linux/input.h>
-#include <sys/ioctl.h>
+Querying device capabilities
+----------------------------
 
-#define BITS_TO_LONGS(x) \
-	(((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long)))
-unsigned long features[BITS_TO_LONGS(FF_CNT)];
-int ioctl(int file_descriptor, int request, unsigned long *features);
+::
+
+    #include <linux/input.h>
+    #include <sys/ioctl.h>
+
+    #define BITS_TO_LONGS(x) \
+	    (((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long)))
+    unsigned long features[BITS_TO_LONGS(FF_CNT)];
+    int ioctl(int file_descriptor, int request, unsigned long *features);
 
 "request" must be EVIOCGBIT(EV_FF, size of features array in bytes )
 
 Returns the features supported by the device. features is a bitfield with the
 following bits:
+
 - FF_CONSTANT	can render constant force effects
 - FF_PERIODIC	can render periodic effects with the following waveforms:
+
   - FF_SQUARE	  square waveform
   - FF_TRIANGLE	  triangle waveform
   - FF_SINE	  sine waveform
   - FF_SAW_UP	  sawtooth up waveform
   - FF_SAW_DOWN	  sawtooth down waveform
   - FF_CUSTOM	  custom waveform
+
 - FF_RAMP       can render ramp effects
 - FF_SPRING	can simulate the presence of a spring
 - FF_FRICTION	can simulate friction
@@ -75,24 +89,30 @@ following bits:
 - FF_GAIN	gain is adjustable
 - FF_AUTOCENTER	autocenter is adjustable
 
-Note: In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All
+.. note::
+
+    - In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All
       devices that support FF_RUMBLE support FF_PERIODIC (square, triangle,
       sine) and the other way around.
 
-Note: The exact syntax FF_CUSTOM is undefined for the time being as no driver
+    - The exact syntax FF_CUSTOM is undefined for the time being as no driver
       supports it yet.
 
+::
 
-int ioctl(int fd, EVIOCGEFFECTS, int *n);
+    int ioctl(int fd, EVIOCGEFFECTS, int *n);
 
 Returns the number of effects the device can keep in its memory.
 
-3.2 Uploading effects to the device
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#include <linux/input.h>
-#include <sys/ioctl.h>
+Uploading effects to the device
+-------------------------------
 
-int ioctl(int file_descriptor, int request, struct ff_effect *effect);
+::
+
+    #include <linux/input.h>
+    #include <sys/ioctl.h>
+
+    int ioctl(int file_descriptor, int request, struct ff_effect *effect);
 
 "request" must be EVIOCSFF.
 
@@ -110,34 +130,41 @@ See <linux/input.h> for a description of the ff_effect struct. You should also
 find help in a few sketches, contained in files shape.fig and interactive.fig.
 You need xfig to visualize these files.
 
-3.3 Removing an effect from the device
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-int ioctl(int fd, EVIOCRMFF, effect.id);
+
+Removing an effect from the device
+----------------------------------
+
+::
+
+    int ioctl(int fd, EVIOCRMFF, effect.id);
 
 This makes room for new effects in the device's memory. Note that this also
 stops the effect if it was playing.
 
-3.4 Controlling the playback of effects
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Controlling the playback of effects
+-----------------------------------
+
 Control of playing is done with write(). Below is an example:
 
-#include <linux/input.h>
-#include <unistd.h>
+::
+
+    #include <linux/input.h>
+    #include <unistd.h>
 
 	struct input_event play;
 	struct input_event stop;
 	struct ff_effect effect;
 	int fd;
-...
+   ...
 	fd = open("/dev/input/eventXX", O_RDWR);
-...
+   ...
 	/* Play three times */
 	play.type = EV_FF;
 	play.code = effect.id;
 	play.value = 3;
 
 	write(fd, (const void*) &play, sizeof(play));
-...
+   ...
 	/* Stop an effect */
 	stop.type = EV_FF;
 	stop.code = effect.id;
@@ -145,43 +172,50 @@ Control of playing is done with write(). Below is an example:
 
 	write(fd, (const void*) &play, sizeof(stop));
 
-3.5 Setting the gain
-~~~~~~~~~~~~~~~~~~~~
+Setting the gain
+----------------
+
 Not all devices have the same strength. Therefore, users should set a gain
 factor depending on how strong they want effects to be. This setting is
 persistent across access to the driver.
 
-/* Set the gain of the device
-int gain;		/* between 0 and 100 */
-struct input_event ie;	/* structure used to communicate with the driver */
+::
 
-ie.type = EV_FF;
-ie.code = FF_GAIN;
-ie.value = 0xFFFFUL * gain / 100;
+    /* Set the gain of the device
+    int gain;		/* between 0 and 100 */
+    struct input_event ie;	/* structure used to communicate with the driver */
 
-if (write(fd, &ie, sizeof(ie)) == -1)
+    ie.type = EV_FF;
+    ie.code = FF_GAIN;
+    ie.value = 0xFFFFUL * gain / 100;
+
+    if (write(fd, &ie, sizeof(ie)) == -1)
 	perror("set gain");
 
-3.6 Enabling/Disabling autocenter
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Enabling/Disabling autocenter
+-----------------------------
+
 The autocenter feature quite disturbs the rendering of effects in my opinion,
 and I think it should be an effect, which computation depends on the game
 type. But you can enable it if you want.
 
-int autocenter;		/* between 0 and 100 */
-struct input_event ie;
+::
 
-ie.type = EV_FF;
-ie.code = FF_AUTOCENTER;
-ie.value = 0xFFFFUL * autocenter / 100;
+    int autocenter;		/* between 0 and 100 */
+    struct input_event ie;
 
-if (write(fd, &ie, sizeof(ie)) == -1)
+    ie.type = EV_FF;
+    ie.code = FF_AUTOCENTER;
+    ie.value = 0xFFFFUL * autocenter / 100;
+
+    if (write(fd, &ie, sizeof(ie)) == -1)
 	perror("set auto-center");
 
 A value of 0 means "no auto-center".
 
-3.7 Dynamic update of an effect
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Dynamic update of an effect
+---------------------------
+
 Proceed as if you wanted to upload a new effect, except that instead of
 setting the id field to -1, you set it to the wanted effect id.
 Normally, the effect is not stopped and restarted. However, depending on the
@@ -192,30 +226,32 @@ case, the driver stops the effect, up-load it, and restart it.
 Therefore it is recommended to dynamically change direction while the effect
 is playing only when it is ok to restart the effect with a replay count of 1.
 
-3.8 Information about the status of effects
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Information about the status of effects
+---------------------------------------
+
 Every time the status of an effect is changed, an event is sent. The values
-and meanings of the fields of the event are as follows:
+and meanings of the fields of the event are as follows::
 
-struct input_event {
-/* When the status of the effect changed */
-	struct timeval time;
+    struct input_event {
+    /* When the status of the effect changed */
+	    struct timeval time;
 
-/* Set to EV_FF_STATUS */
-	unsigned short type;
+    /* Set to EV_FF_STATUS */
+	    unsigned short type;
 
-/* Contains the id of the effect */
-	unsigned short code;
+    /* Contains the id of the effect */
+	    unsigned short code;
 
-/* Indicates the status */
-	unsigned int value;
-};
+    /* Indicates the status */
+	    unsigned int value;
+    };
 
-FF_STATUS_STOPPED	The effect stopped playing
-FF_STATUS_PLAYING	The effect started to play
+    FF_STATUS_STOPPED	The effect stopped playing
+    FF_STATUS_PLAYING	The effect started to play
 
-NOTE: Status feedback is only supported by iforce driver. If you have
+.. note::
+
+    - Status feedback is only supported by iforce driver. If you have
       a really good reason to use this, please contact
       linux-joystick@atrey.karlin.mff.cuni.cz or anssi.hannula@gmail.com
       so that support for it can be added to the rest of the drivers.
-
-- 
2.9.3

[PATCH v2 13/37] docs: input/gamepad: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/gamepad.txt | 43 +++++++++++++++++++++++++++++------------
 1 file changed, 31 insertions(+), 12 deletions(-)

diff --git a/Documentation/input/gamepad.txt b/Documentation/input/gamepad.txt
index 3f6d8a5e9cdc..8bc7fdea3705 100644
--- a/Documentation/input/gamepad.txt
+++ b/Documentation/input/gamepad.txt
@@ -1,5 +1,9 @@
-                            Linux Gamepad API
-----------------------------------------------------------------------------
+-----------------
+Linux Gamepad API
+-----------------
+
+:Author: 2013 by David Herrmann <dh.herrmann@gmail.com>
+
 
 1. Intro
 ~~~~~~~~
@@ -9,7 +13,7 @@ document defines how gamepads are supposed to report their data.
 
 2. Geometry
 ~~~~~~~~~~~
-As "gamepad" we define devices which roughly look like this:
+As "gamepad" we define devices which roughly look like this::
 
             ____________________________              __
            / [__ZL__]          [__ZR__] \               |
@@ -35,6 +39,7 @@ As "gamepad" we define devices which roughly look like this:
                       Menu Pad
 
 Most gamepads have the following features:
+
   - Action-Pad
     4 buttons in diamonds-shape (on the right side). The buttons are
     differently labeled on most devices so we define them as NORTH,
@@ -60,6 +65,7 @@ Most gamepads have the following features:
 
 3. Detection
 ~~~~~~~~~~~~
+
 All gamepads that follow the protocol described here map BTN_GAMEPAD. This is
 an alias for BTN_SOUTH/BTN_A. It can be used to identify a gamepad as such.
 However, not all gamepads provide all features, so you need to test for all
@@ -87,6 +93,7 @@ events.
 
 4. Events
 ~~~~~~~~~
+
 Gamepads report the following events:
 
 Action-Pad:
@@ -94,8 +101,10 @@ Action-Pad:
   device reports BTN_SOUTH (which BTN_GAMEPAD is an alias for). Regardless
   of the labels on the buttons, the codes are sent according to the
   physical position of the buttons.
+
   Please note that 2- and 3-button pads are fairly rare and old. You might
   want to filter gamepads that do not report all four.
+
     2-Button Pad:
       If only 2 action-buttons are present, they are reported as BTN_SOUTH and
       BTN_EAST. For vertical layouts, the upper button is BTN_EAST. For
@@ -118,42 +127,52 @@ D-Pad:
   may even report both. The kernel does not convert between these so
   applications should support both and choose what is more appropriate if
   both are reported.
+
     Digital buttons are reported as:
+
       BTN_DPAD_*
+
     Analog buttons are reported as:
+
       ABS_HAT0X and ABS_HAT0Y
-      (for ABS values negative is left/up, positive is right/down)
+
+  (for ABS values negative is left/up, positive is right/down)
 
 Analog-Sticks:
   The left analog-stick is reported as ABS_X, ABS_Y. The right analog stick is
   reported as ABS_RX, ABS_RY. Zero, one or two sticks may be present.
   If analog-sticks provide digital buttons, they are mapped accordingly as
   BTN_THUMBL (first/left) and BTN_THUMBR (second/right).
-    (for ABS values negative is left/up, positive is right/down)
+
+  (for ABS values negative is left/up, positive is right/down)
 
 Triggers:
   Trigger buttons can be available as digital or analog buttons or both. User-
   space must correctly deal with any situation and choose the most appropriate
   mode.
+
   Upper trigger buttons are reported as BTN_TR or ABS_HAT1X (right) and BTN_TL
   or ABS_HAT1Y (left). Lower trigger buttons are reported as BTN_TR2 or
   ABS_HAT2X (right/ZR) and BTN_TL2 or ABS_HAT2Y (left/ZL).
+
   If only one trigger-button combination is present (upper+lower), they are
   reported as "right" triggers (BTN_TR/ABS_HAT1X).
-    (ABS trigger values start at 0, pressure is reported as positive values)
+
+  (ABS trigger values start at 0, pressure is reported as positive values)
 
 Menu-Pad:
   Menu buttons are always digital and are mapped according to their location
   instead of their labels. That is:
-    1-button Pad: Mapped as BTN_START
-    2-button Pad: Left button mapped as BTN_SELECT, right button mapped as
-                  BTN_START
+
+    1-button Pad:
+	Mapped as BTN_START
+
+    2-button Pad:
+	Left button mapped as BTN_SELECT, right button mapped as BTN_START
+
   Many pads also have a third button which is branded or has a special symbol
   and meaning. Such buttons are mapped as BTN_MODE. Examples are the Nintendo
   "HOME" button, the XBox "X"-button or Sony "PS" button.
 
 Rumble:
   Rumble is advertised as FF_RUMBLE.
-
-----------------------------------------------------------------------------
-  Written 2013 by David Herrmann <dh.herrmann@gmail.com>
-- 
2.9.3

[PATCH v2 14/37] docs: input/gameport-programming: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST.

Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/gameport-programming.txt | 83 ++++++++++++++++++++--------
 1 file changed, 59 insertions(+), 24 deletions(-)

diff --git a/Documentation/input/gameport-programming.txt b/Documentation/input/gameport-programming.txt
index 03a74fc3b496..c96911df1c54 100644
--- a/Documentation/input/gameport-programming.txt
+++ b/Documentation/input/gameport-programming.txt
@@ -1,11 +1,12 @@
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Programming gameport drivers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-1. A basic classic gameport
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A basic classic gameport
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 If the gameport doesn't provide more than the inb()/outb() functionality,
-the code needed to register it with the joystick drivers is simple:
+the code needed to register it with the joystick drivers is simple::
 
 	struct gameport gameport;
 
@@ -37,12 +38,12 @@ space only when something really is using it. Disable it again in the
 callback, so that it doesn't fail if some of the possible addresses are
 already occupied by other gameports.
 
-2. Memory mapped gameport
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Memory mapped gameport
+~~~~~~~~~~~~~~~~~~~~~~
 
 When a gameport can be accessed through MMIO, this way is preferred, because
 it is faster, allowing more reads per second. Registering such a gameport
-isn't as easy as a basic IO one, but not so much complex:
+isn't as easy as a basic IO one, but not so much complex::
 
 	struct gameport gameport;
 
@@ -53,19 +54,21 @@ isn't as easy as a basic IO one, but not so much complex:
 
 	unsigned char my_read(struct gameport *gameport)
 	{
-		return my_mmio;	
+		return my_mmio;
 	}
 
 	gameport.read = my_read;
 	gameport.trigger = my_trigger;
 	gameport_register_port(&gameport);
 
-3. Cooked mode gameport
-~~~~~~~~~~~~~~~~~~~~~~~
+.. _gameport_pgm_cooked_mode:
+
+Cooked mode gameport
+~~~~~~~~~~~~~~~~~~~~
 
 There are gameports that can report the axis values as numbers, that means
 the driver doesn't have to measure them the old way - an ADC is built into
-the gameport. To register a cooked gameport:
+the gameport. To register a cooked gameport::
 
 	struct gameport gameport;
 
@@ -95,8 +98,8 @@ See analog.c and input.c for handling of fuzz - the fuzz value determines
 the size of a gaussian filter window that is used to eliminate the noise
 in the data.
 
-4. More complex gameports
-~~~~~~~~~~~~~~~~~~~~~~~~~
+More complex gameports
+~~~~~~~~~~~~~~~~~~~~~~
 
 Gameports can support both raw and cooked modes. In that case combine either
 examples 1+2 or 1+3. Gameports can support internal calibration - see below,
@@ -104,65 +107,91 @@ and also lightning.c and analog.c on how that works. If your driver supports
 more than one gameport instance simultaneously, use the ->private member of
 the gameport struct to point to your data.
 
-5. Unregistering a gameport
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Unregistering a gameport
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-Simple:
+Simple::
 
-gameport_unregister_port(&gameport);
+    gameport_unregister_port(&gameport);
 
-6. The gameport structure
-~~~~~~~~~~~~~~~~~~~~~~~~~
+The gameport structure
+~~~~~~~~~~~~~~~~~~~~~~
 
-struct gameport {
+.. note::
+
+    This section is outdated. There are several fields here that don't
+    match what's there at include/linux/gameport.h.
+
+::
+
+    struct gameport {
 
 	void *private;
 
 A private pointer for free use in the gameport driver. (Not the joystick
 driver!)
 
+::
+
 	int number;
 
 Number assigned to the gameport when registered. Informational purpose only.
 
+::
+
 	int io;
 
 I/O address for use with raw mode. You have to either set this, or ->read()
 to some value if your gameport supports raw mode.
 
+::
+
 	int speed;
 
 Raw mode speed of the gameport reads in thousands of reads per second.
 
+::
+
 	int fuzz;
 
 If the gameport supports cooked mode, this should be set to a value that
-represents the amount of noise in the data. See section 3.
+represents the amount of noise in the data. See
+:ref:`gameport_pgm_cooked_mode`.
+
+::
 
 	void (*trigger)(struct gameport *);
 
 Trigger. This function should trigger the ns558 oneshots. If set to NULL,
 outb(0xff, io) will be used.
 
+::
+
 	unsigned char (*read)(struct gameport *);
 
 Read the buttons and ns558 oneshot bits. If set to NULL, inb(io) will be
 used instead.
 
-	int (*cooked_read)(struct gameport *, int *axes, int *buttons);	
+::
+
+	int (*cooked_read)(struct gameport *, int *axes, int *buttons);
 
 If the gameport supports cooked mode, it should point this to its cooked
 read function. It should fill axes[0..3] with four values of the joystick axes
 and buttons[0] with four bits representing the buttons.
 
-	int (*calibrate)(struct gameport *, int *axes, int *max); 
+::
+
+	int (*calibrate)(struct gameport *, int *axes, int *max);
 
 Function for calibrating the ADC hardware. When called, axes[0..3] should be
 pre-filled by cooked data by the caller, max[0..3] should be pre-filled with
 expected maximums for each axis. The calibrate() function should set the
 sensitivity of the ADC hardware so that the maximums fit in its range and
 recompute the axes[] values to match the new sensitivity or re-read them from
-the hardware so that they give valid values. 
+the hardware so that they give valid values.
+
+::
 
 	int (*open)(struct gameport *, int mode);
 
@@ -172,16 +201,22 @@ Second, resource allocation can happen here. The port can also be enabled
 here. Prior to this call, other fields of the gameport struct (namely the io
 member) need not to be valid.
 
+::
+
 	void (*close)(struct gameport *);
 
 Close() should free the resources allocated by open, possibly disabling the
 gameport.
 
+::
+
 	struct gameport_dev *dev;
 	struct gameport *next;
 
 For internal use by the gameport layer.
 
-};
+::
+
+    };
 
 Enjoy!
-- 
2.9.3

[PATCH v2 15/37] docs: input/gpio-tilt: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/gpio-tilt.txt | 124 +++++++++++++++++++-------------------
 1 file changed, 62 insertions(+), 62 deletions(-)

diff --git a/Documentation/input/gpio-tilt.txt b/Documentation/input/gpio-tilt.txt
index 2cdfd9bcb1af..23de9eff6a34 100644
--- a/Documentation/input/gpio-tilt.txt
+++ b/Documentation/input/gpio-tilt.txt
@@ -28,76 +28,76 @@ 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) {
-	/* code to enable the sensors */
-};
+    static int sg060_tilt_enable(struct device *dev) {
+	    /* code to enable the sensors */
+    };
 
-static void sg060_tilt_disable(struct device *dev) {
-	/* code to disable the sensors */
-};
+    static void sg060_tilt_disable(struct device *dev) {
+	    /* code to disable the sensors */
+    };
 
-static struct gpio sg060_tilt_gpios[] = {
-	{ SG060_TILT_GPIO_SENSOR1, GPIOF_IN, "tilt_sensor1" },
-	{ SG060_TILT_GPIO_SENSOR2, GPIOF_IN, "tilt_sensor2" },
-};
+    static struct gpio sg060_tilt_gpios[] = {
+	    { SG060_TILT_GPIO_SENSOR1, GPIOF_IN, "tilt_sensor1" },
+	    { SG060_TILT_GPIO_SENSOR2, GPIOF_IN, "tilt_sensor2" },
+    };
 
-static struct gpio_tilt_state sg060_tilt_states[] = {
-	{
-		.gpios = (0 << 1) | (0 << 0),
-		.axes = (int[]) {
-			0,
-		},
-	}, {
-		.gpios = (0 << 1) | (1 << 0),
-		.axes = (int[]) {
-			1, /* 90 degrees */
-		},
-	}, {
-		.gpios = (1 << 1) | (1 << 0),
-		.axes = (int[]) {
-			2, /* 180 degrees */
-		},
-	}, {
-		.gpios = (1 << 1) | (0 << 0),
-		.axes = (int[]) {
-			3, /* 270 degrees */
-		},
-	},
-};
+    static struct gpio_tilt_state sg060_tilt_states[] = {
+	    {
+		    .gpios = (0 << 1) | (0 << 0),
+		    .axes = (int[]) {
+			    0,
+		    },
+	    }, {
+		    .gpios = (0 << 1) | (1 << 0),
+		    .axes = (int[]) {
+			    1, /* 90 degrees */
+		    },
+	    }, {
+		    .gpios = (1 << 1) | (1 << 0),
+		    .axes = (int[]) {
+			    2, /* 180 degrees */
+		    },
+	    }, {
+		    .gpios = (1 << 1) | (0 << 0),
+		    .axes = (int[]) {
+			    3, /* 270 degrees */
+		    },
+	    },
+    };
 
-static struct gpio_tilt_axis sg060_tilt_axes[] = {
-	{
-		.axis = ABS_RY,
-		.min = 0,
-		.max = 3,
-		.fuzz = 0,
-		.flat = 0,
-	},
-};
+    static struct gpio_tilt_axis sg060_tilt_axes[] = {
+	    {
+		    .axis = ABS_RY,
+		    .min = 0,
+		    .max = 3,
+		    .fuzz = 0,
+		    .flat = 0,
+	    },
+    };
 
-static struct gpio_tilt_platform_data sg060_tilt_pdata= {
-	.gpios = sg060_tilt_gpios,
-	.nr_gpios = ARRAY_SIZE(sg060_tilt_gpios),
+    static struct gpio_tilt_platform_data sg060_tilt_pdata= {
+	    .gpios = sg060_tilt_gpios,
+	    .nr_gpios = ARRAY_SIZE(sg060_tilt_gpios),
 
-	.axes = sg060_tilt_axes,
-	.nr_axes = ARRAY_SIZE(sg060_tilt_axes),
+	    .axes = sg060_tilt_axes,
+	    .nr_axes = ARRAY_SIZE(sg060_tilt_axes),
 
-	.states = sg060_tilt_states,
-	.nr_states = ARRAY_SIZE(sg060_tilt_states),
+	    .states = sg060_tilt_states,
+	    .nr_states = ARRAY_SIZE(sg060_tilt_states),
 
-	.debounce_interval = 100,
+	    .debounce_interval = 100,
 
-	.poll_interval = 1000,
-	.enable = sg060_tilt_enable,
-	.disable = sg060_tilt_disable,
-};
+	    .poll_interval = 1000,
+	    .enable = sg060_tilt_enable,
+	    .disable = sg060_tilt_disable,
+    };
 
-static struct platform_device sg060_device_tilt = {
-	.name = "gpio-tilt-polled",
-	.id = -1,
-	.dev = {
-		.platform_data = &sg060_tilt_pdata,
-	},
-};
+    static struct platform_device sg060_device_tilt = {
+	    .name = "gpio-tilt-polled",
+	    .id = -1,
+	    .dev = {
+		    .platform_data = &sg060_tilt_pdata,
+	    },
+    };
-- 
2.9.3

[PATCH v2 16/37] docs: input/iforce-protocol: convert it to ReST format

[Mauro Carvalho Chehab]

This file seems to be using some other markup language,
(maybe mediawiki?). Manually convert it to ReST markup,
with is the one we're using along the Kernel documentaiton.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/iforce-protocol.txt | 495 ++++++++++++++++++++------------
 1 file changed, 309 insertions(+), 186 deletions(-)

diff --git a/Documentation/input/iforce-protocol.txt b/Documentation/input/iforce-protocol.txt
index 66287151c54a..8634beac3fdb 100644
--- a/Documentation/input/iforce-protocol.txt
+++ b/Documentation/input/iforce-protocol.txt
@@ -1,4 +1,17 @@
-** 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,238 +19,350 @@ 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
-   Upper 4 bits: Hat
-07 Rudder
-
-** Device effects states
-OP= 02
-LEN= Varies
-00 ? Bit 1 (Value 2) is the value of the deadman switch
-01 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id.
-02 ??
-03 Address of parameter block changed (lsb)
-04 Address of parameter block changed (msb)
-05 Address of second parameter block changed (lsb)
-... depending on the number of parameter blocks updated
-
-** Force effect **
-OP=  01
-LEN= 0e
-00 Channel (when playing several effects at the same time, each must be assigned a channel)
-01 Wave form
-	Val 00 Constant
-	Val 20 Square
-	Val 21 Triangle
-	Val 22 Sine
-	Val 23 Sawtooth up
-	Val 24 Sawtooth down
-	Val 40 Spring (Force = f(pos))
-	Val 41 Friction (Force = f(velocity)) and Inertia (Force = f(acceleration))
-
-
-02 Axes affected and trigger
-	Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction
-	          Val 4 = X axis only. Byte 05 must contain 5a
-	          Val 8 = Y axis only. Byte 05 must contain b4
-	          Val c = X and Y axes. Bytes 05 must contain 60
-	Bits 0-3: Val 0 = No trigger
-	          Val x+1 = Button x triggers the effect
-	When the whole byte is 0, cancel the previously set trigger
-
-03-04 Duration of effect (little endian encoding, in ms)
-
-05 Direction of effect, if applicable. Else, see 02 for value to assign.
-
-06-07 Minimum time between triggering.
-
-08-09 Address of periodicity or magnitude parameters
-0a-0b Address of attack and fade parameters, or ffff if none.
-*or*
-08-09 Address of interactive parameters for X-axis, or ffff if not applicable
-0a-0b Address of interactive parameters for Y-axis, or ffff if not applicable
-
-0c-0d Delay before execution of effect (little endian encoding, in ms)
-
-
-** Time based parameters **
-
-*** Attack and fade ***
-OP=  02
-LEN= 08
-00-01 Address where to store the parameters
-02-03 Duration of attack (little endian encoding, in ms)
-04 Level at end of attack. Signed byte.
-05-06 Duration of fade.
-07 Level at end of fade.
-
-*** Magnitude ***
-OP=  03
-LEN= 03
-00-01 Address
-02 Level. Signed byte.
-
-*** Periodicity ***
-OP=  04
-LEN= 07
-00-01 Address
-02 Magnitude. Signed byte.
-03 Offset. Signed byte.
-04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
-05-06 Period (little endian encoding, in ms)
-
-** Interactive parameters **
-OP=  05
-LEN= 0a
-00-01 Address
-02 Positive Coeff
-03 Negative Coeff
-04+05 Offset (center)
-06+07 Dead band (Val 01F4 = 5000 (decimal))
-08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal))
-09 Negative saturation
+axis::
+
+    OP= 01 for a joystick, 03 for a wheel
+    LEN= Varies from device to device
+    00 X-Axis lsb
+    01 X-Axis msb
+    02 Y-Axis lsb, or gas pedal for a wheel
+    03 Y-Axis msb, or brake pedal for a wheel
+    04 Throttle
+    05 Buttons
+    06 Lower 4 bits: Buttons
+       Upper 4 bits: Hat
+    07 Rudder
+
+Device effects states
+=====================
+
+::
+
+    OP= 02
+    LEN= Varies
+    00 ? Bit 1 (Value 2) is the value of the deadman switch
+    01 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id.
+    02 ??
+    03 Address of parameter block changed (lsb)
+    04 Address of parameter block changed (msb)
+    05 Address of second parameter block changed (lsb)
+    ... depending on the number of parameter blocks updated
+
+Force effect
+------------
+
+::
+
+    OP=  01
+    LEN= 0e
+    00 Channel (when playing several effects at the same time, each must
+                be assigned a channel)
+    01 Wave form
+	    Val 00 Constant
+	    Val 20 Square
+	    Val 21 Triangle
+	    Val 22 Sine
+	    Val 23 Sawtooth up
+	    Val 24 Sawtooth down
+	    Val 40 Spring (Force = f(pos))
+	    Val 41 Friction (Force = f(velocity)) and Inertia
+	           (Force = f(acceleration))
+
+
+    02 Axes affected and trigger
+	    Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction
+		    Val 4 = X axis only. Byte 05 must contain 5a
+		    Val 8 = Y axis only. Byte 05 must contain b4
+		    Val c = X and Y axes. Bytes 05 must contain 60
+	    Bits 0-3: Val 0 = No trigger
+		    Val x+1 = Button x triggers the effect
+	    When the whole byte is 0, cancel the previously set trigger
+
+    03-04 Duration of effect (little endian encoding, in ms)
+
+    05 Direction of effect, if applicable. Else, see 02 for value to assign.
+
+    06-07 Minimum time between triggering.
+
+    08-09 Address of periodicity or magnitude parameters
+    0a-0b Address of attack and fade parameters, or ffff if none.
+    *or*
+    08-09 Address of interactive parameters for X-axis,
+          or ffff if not applicable
+    0a-0b Address of interactive parameters for Y-axis,
+	  or ffff if not applicable
+
+    0c-0d Delay before execution of effect (little endian encoding, in ms)
+
+
+Time based parameters
+---------------------
+
+Attack and fade
+^^^^^^^^^^^^^^^
+
+::
+
+    OP=  02
+    LEN= 08
+    00-01 Address where to store the parameters
+    02-03 Duration of attack (little endian encoding, in ms)
+    04 Level at end of attack. Signed byte.
+    05-06 Duration of fade.
+    07 Level at end of fade.
+
+Magnitude
+^^^^^^^^^
+
+::
+
+    OP=  03
+    LEN= 03
+    00-01 Address
+    02 Level. Signed byte.
+
+Periodicity
+^^^^^^^^^^^
+
+::
+
+    OP=  04
+    LEN= 07
+    00-01 Address
+    02 Magnitude. Signed byte.
+    03 Offset. Signed byte.
+    04 Phase. Val 00 = 0 deg, Val 40 = 90 degs.
+    05-06 Period (little endian encoding, in ms)
+
+Interactive parameters
+----------------------
+
+::
+
+    OP=  05
+    LEN= 0a
+    00-01 Address
+    02 Positive Coeff
+    03 Negative Coeff
+    04+05 Offset (center)
+    06+07 Dead band (Val 01F4 = 5000 (decimal))
+    08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal))
+    09 Negative saturation
 
 The encoding is a bit funny here: For coeffs, these are signed values. The
 maximum value is 64 (100 decimal), the min is 9c.
 For the offset, the minimum value is FE0C, the maximum value is 01F4.
 For the deadband, the minimum value is 0, the max is 03E8.
 
-** Controls **
-OP=  41
-LEN= 03
-00 Channel
-01 Start/Stop
-	Val 00: Stop
-	Val 01: Start and play once.
-	Val 41: Start and play n times (See byte 02 below)
-02 Number of iterations n.
-
-** Init **
-
-*** Querying features ***
-OP=  ff
-Query command. Length varies according to the query type.
-The general format of this packet is:
-ff 01 QUERY [INDEX] CHECKSUM
-responses are of the same form:
-FF LEN QUERY VALUE_QUERIED CHECKSUM2
-where LEN = 1 + length(VALUE_QUERIED)
-
-**** Query ram size ****
-QUERY = 42 ('B'uffer size)
+Controls
+--------
+
+::
+
+    OP=  41
+    LEN= 03
+    00 Channel
+    01 Start/Stop
+	    Val 00: Stop
+	    Val 01: Start and play once.
+	    Val 41: Start and play n times (See byte 02 below)
+    02 Number of iterations n.
+
+Init
+----
+
+
+Querying features
+^^^^^^^^^^^^^^^^^
+::
+
+    OP=  ff
+    Query command. Length varies according to the query type.
+    The general format of this packet is:
+    ff 01 QUERY [INDEX] CHECKSUM
+    responses are of the same form:
+    FF LEN QUERY VALUE_QUERIED CHECKSUM2
+    where LEN = 1 + length(VALUE_QUERIED)
+
+Query ram size
+~~~~~~~~~~~~~~
+
+::
+
+    QUERY = 42 ('B'uffer size)
+
 The device should reply with the same packet plus two additional bytes
 containing the size of the memory:
 ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available.
 
-**** Query number of effects ****
-QUERY = 4e ('N'umber of effects)
+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 ***
-
-**** Set Control ****
-!!! Device dependent, can be different on different models !!!
-OP=  40 <idx> <val> [<val>]
-LEN= 2 or 3
-00 Idx
-   Idx 00 Set dead zone (0..2048)
-   Idx 01 Ignore Deadman sensor (0..1)
-   Idx 02 Enable comm watchdog (0..1)
-   Idx 03 Set the strength of the spring (0..100)
-   Idx 04 Enable or disable the spring (0/1)
-   Idx 05 Set axis saturation threshold (0..2048)
-
-**** Set Effect State ****
-OP=  42 <val>
-LEN= 1
-00 State
-   Bit 3 Pause force feedback
-   Bit 2 Enable force feedback
-   Bit 0 Stop all effects
-
-**** Set overall gain ****
-OP=  43 <val>
-LEN= 1
-00 Gain
-   Val 00 = 0%
-   Val 40 = 50%
-   Val 80 = 100%
-
-** Parameter memory **
+Initialisation of the device
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set Control
+~~~~~~~~~~~
+
+.. note::
+    Device dependent, can be different on different models!
+
+::
+
+    OP=  40 <idx> <val> [<val>]
+    LEN= 2 or 3
+    00 Idx
+       Idx 00 Set dead zone (0..2048)
+       Idx 01 Ignore Deadman sensor (0..1)
+       Idx 02 Enable comm watchdog (0..1)
+       Idx 03 Set the strength of the spring (0..100)
+       Idx 04 Enable or disable the spring (0/1)
+       Idx 05 Set axis saturation threshold (0..2048)
+
+Set Effect State
+~~~~~~~~~~~~~~~~
+
+::
+
+    OP=  42 <val>
+    LEN= 1
+    00 State
+       Bit 3 Pause force feedback
+       Bit 2 Enable force feedback
+       Bit 0 Stop all effects
+
+Set overall
+~~~~~~~~~~~
+
+::
+
+    OP=  43 <val>
+    LEN= 1
+    00 Gain
+       Val 00 = 0%
+       Val 40 = 50%
+       Val 80 = 100%
+
+Parameter memory
+----------------
 
 Each device has a certain amount of memory to store parameters of effects.
 The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below
 is the amount of memory apparently needed for every set of parameters:
+
  - period : 0c
  - magnitude : 02
  - attack and fade : 0e
  - interactive : 08
 
-** Appendix: How to study the protocol ? **
+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: 
+1. Generate effects using the force editor provided with the DirectX SDK, or
+use Immersion Studio (freely available at their web site in the developer section:
 www.immersion.com)
-2. Start a soft spying RS232 or USB (depending on where you connected your 
+2. Start a soft spying RS232 or USB (depending on where you connected your
 joystick/wheel). I used ComPortSpy from fCoder (alpha version!)
 3. Play the effect, and watch what happens on the spy screen.
 
@@ -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.
-- 
2.9.3

[PATCH v2 17/37] docs: input/input-programming: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/input-programming.txt | 253 +++++++++++++++---------------
 1 file changed, 128 insertions(+), 125 deletions(-)

diff --git a/Documentation/input/input-programming.txt b/Documentation/input/input-programming.txt
index 7f8b9d97bc47..4d3b22222e93 100644
--- a/Documentation/input/input-programming.txt
+++ b/Documentation/input/input-programming.txt
@@ -1,77 +1,78 @@
+~~~~~~~~~~~~~~~~~~~~~~~~~
 Programming input drivers
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-1. Creating an input device driver
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Creating an input device driver
+===============================
 
-1.0 The simplest example
-~~~~~~~~~~~~~~~~~~~~~~~~
+The simplest example
+~~~~~~~~~~~~~~~~~~~~
 
 Here comes a very simple example of an input device driver. The device has
 just one button and the button is accessible at i/o port BUTTON_PORT. When
-pressed or released a BUTTON_IRQ happens. The driver could look like:
-
-#include <linux/input.h>
-#include <linux/module.h>
-#include <linux/init.h>
-
-#include <asm/irq.h>
-#include <asm/io.h>
-
-static struct input_dev *button_dev;
-
-static irqreturn_t button_interrupt(int irq, void *dummy)
-{
-	input_report_key(button_dev, BTN_0, inb(BUTTON_PORT) & 1);
-	input_sync(button_dev);
-	return IRQ_HANDLED;
-}
-
-static int __init button_init(void)
-{
-	int error;
-
-	if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) {
-                printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq);
-                return -EBUSY;
-        }
-
-	button_dev = input_allocate_device();
-	if (!button_dev) {
-		printk(KERN_ERR "button.c: Not enough memory\n");
-		error = -ENOMEM;
-		goto err_free_irq;
-	}
-
-	button_dev->evbit[0] = BIT_MASK(EV_KEY);
-	button_dev->keybit[BIT_WORD(BTN_0)] = BIT_MASK(BTN_0);
-
-	error = input_register_device(button_dev);
-	if (error) {
-		printk(KERN_ERR "button.c: Failed to register device\n");
-		goto err_free_dev;
-	}
-
-	return 0;
-
- err_free_dev:
-	input_free_device(button_dev);
- err_free_irq:
-	free_irq(BUTTON_IRQ, button_interrupt);
-	return error;
-}
-
-static void __exit button_exit(void)
-{
-        input_unregister_device(button_dev);
-	free_irq(BUTTON_IRQ, button_interrupt);
-}
-
-module_init(button_init);
-module_exit(button_exit);
-
-1.1 What the example does
-~~~~~~~~~~~~~~~~~~~~~~~~~
+pressed or released a BUTTON_IRQ happens. The driver could look like::
+
+    #include <linux/input.h>
+    #include <linux/module.h>
+    #include <linux/init.h>
+
+    #include <asm/irq.h>
+    #include <asm/io.h>
+
+    static struct input_dev *button_dev;
+
+    static irqreturn_t button_interrupt(int irq, void *dummy)
+    {
+	    input_report_key(button_dev, BTN_0, inb(BUTTON_PORT) & 1);
+	    input_sync(button_dev);
+	    return IRQ_HANDLED;
+    }
+
+    static int __init button_init(void)
+    {
+	    int error;
+
+	    if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) {
+		    printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq);
+		    return -EBUSY;
+	    }
+
+	    button_dev = input_allocate_device();
+	    if (!button_dev) {
+		    printk(KERN_ERR "button.c: Not enough memory\n");
+		    error = -ENOMEM;
+		    goto err_free_irq;
+	    }
+
+	    button_dev->evbit[0] = BIT_MASK(EV_KEY);
+	    button_dev->keybit[BIT_WORD(BTN_0)] = BIT_MASK(BTN_0);
+
+	    error = input_register_device(button_dev);
+	    if (error) {
+		    printk(KERN_ERR "button.c: Failed to register device\n");
+		    goto err_free_dev;
+	    }
+
+	    return 0;
+
+    err_free_dev:
+	    input_free_device(button_dev);
+    err_free_irq:
+	    free_irq(BUTTON_IRQ, button_interrupt);
+	    return error;
+    }
+
+    static void __exit button_exit(void)
+    {
+	    input_unregister_device(button_dev);
+	    free_irq(BUTTON_IRQ, button_interrupt);
+    }
+
+    module_init(button_init);
+    module_exit(button_exit);
+
+What the example does
+~~~~~~~~~~~~~~~~~~~~~
 
 First it has to include the <linux/input.h> file, which interfaces to the
 input subsystem. This provides all the definitions needed.
@@ -85,7 +86,7 @@ and sets up input bitfields. This way the device driver tells the other
 parts of the input systems what it is - what events can be generated or
 accepted by this input device. Our example device can only generate EV_KEY
 type events, and from those only BTN_0 event code. Thus we only set these
-two bits. We could have used
+two bits. We could have used::
 
 	set_bit(EV_KEY, button_dev.evbit);
 	set_bit(BTN_0, button_dev.keybit);
@@ -93,7 +94,7 @@ two bits. We could have used
 as well, but with more than single bits the first approach tends to be
 shorter.
 
-Then the example driver registers the input device structure by calling
+Then the example driver registers the input device structure by calling::
 
 	input_register_device(&button_dev);
 
@@ -102,12 +103,12 @@ calls device handler modules _connect functions to tell them a new input
 device has appeared. input_register_device() may sleep and therefore must
 not be called from an interrupt or with a spinlock held.
 
-While in use, the only used function of the driver is
+While in use, the only used function of the driver is::
 
 	button_interrupt()
 
 which upon every interrupt from the button checks its state and reports it
-via the
+via the::
 
 	input_report_key()
 
@@ -116,7 +117,7 @@ routine isn't reporting two same value events (press, press for example) to
 the input system, because the input_report_* functions check that
 themselves.
 
-Then there is the
+Then there is the::
 
 	input_sync()
 
@@ -125,38 +126,38 @@ This doesn't seem important in the one button case, but is quite important
 for for example mouse movement, where you don't want the X and Y values
 to be interpreted separately, because that'd result in a different movement.
 
-1.2 dev->open() and dev->close()
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+dev->open() and dev->close()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In case the driver has to repeatedly poll the device, because it doesn't
 have an interrupt coming from it and the polling is too expensive to be done
 all the time, or if the device uses a valuable resource (eg. interrupt), it
 can use the open and close callback to know when it can stop polling or
 release the interrupt and when it must resume polling or grab the interrupt
-again. To do that, we would add this to our example driver:
+again. To do that, we would add this to our example driver::
 
-static int button_open(struct input_dev *dev)
-{
-	if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) {
-                printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq);
-                return -EBUSY;
-        }
+    static int button_open(struct input_dev *dev)
+    {
+	    if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) {
+		    printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq);
+		    return -EBUSY;
+	    }
 
-        return 0;
-}
+	    return 0;
+    }
 
-static void button_close(struct input_dev *dev)
-{
-        free_irq(IRQ_AMIGA_VERTB, button_interrupt);
-}
+    static void button_close(struct input_dev *dev)
+    {
+	    free_irq(IRQ_AMIGA_VERTB, button_interrupt);
+    }
 
-static int __init button_init(void)
-{
-	...
-	button_dev->open = button_open;
-	button_dev->close = button_close;
-	...
-}
+    static int __init button_init(void)
+    {
+	    ...
+	    button_dev->open = button_open;
+	    button_dev->close = button_close;
+	    ...
+    }
 
 Note that input core keeps track of number of users for the device and
 makes sure that dev->open() is called only when the first user connects
@@ -166,11 +167,11 @@ disconnects. Calls to both callbacks are serialized.
 The open() callback should return a 0 in case of success or any nonzero value
 in case of failure. The close() callback (which is void) must always succeed.
 
-1.3 Basic event types
-~~~~~~~~~~~~~~~~~~~~~
+Basic event types
+~~~~~~~~~~~~~~~~~
 
 The most simple event type is EV_KEY, which is used for keys and buttons.
-It's reported to the input system via:
+It's reported to the input system via::
 
 	input_report_key(struct input_dev *dev, int code, int value)
 
@@ -188,7 +189,7 @@ events are namely for joysticks and digitizers - devices that do work in an
 absolute coordinate systems.
 
 Having the device report EV_REL buttons is as simple as with EV_KEY, simply
-set the corresponding bits and call the
+set the corresponding bits and call the::
 
 	input_report_rel(struct input_dev *dev, int code, int value)
 
@@ -197,14 +198,14 @@ function. Events are generated only for nonzero value.
 However EV_ABS requires a little special care. Before calling
 input_register_device, you have to fill additional fields in the input_dev
 struct for each absolute axis your device has. If our button device had also
-the ABS_X axis:
+the ABS_X axis::
 
 	button_dev.absmin[ABS_X] = 0;
 	button_dev.absmax[ABS_X] = 255;
 	button_dev.absfuzz[ABS_X] = 4;
 	button_dev.absflat[ABS_X] = 8;
 
-Or, you can just say:
+Or, you can just say::
 
 	input_set_abs_params(button_dev, ABS_X, 0, 255, 4, 8);
 
@@ -218,18 +219,18 @@ If you don't need absfuzz and absflat, you can set them to zero, which mean
 that the thing is precise and always returns to exactly the center position
 (if it has any).
 
-1.4 BITS_TO_LONGS(), BIT_WORD(), BIT_MASK()
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+BITS_TO_LONGS(), BIT_WORD(), BIT_MASK()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These three macros from bitops.h help some bitfield computations:
+These three macros from bitops.h help some bitfield computations::
 
 	BITS_TO_LONGS(x) - returns the length of a bitfield array in longs for
 			   x bits
 	BIT_WORD(x)	 - returns the index in the array in longs for bit x
 	BIT_MASK(x)	 - returns the index in a long for bit x
 
-1.5 The id* and name fields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The id* and name fields
+~~~~~~~~~~~~~~~~~~~~~~~
 
 The dev->name should be set before registering the input device by the input
 device driver. It's a string like 'Generic button device' containing a
@@ -245,8 +246,8 @@ driver.
 
 The id and name fields can be passed to userland via the evdev interface.
 
-1.6 The keycode, keycodemax, keycodesize fields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The keycode, keycodemax, keycodesize fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These three fields should be used by input devices that have dense keymaps.
 The keycode is an array used to map from scancodes to input system keycodes.
@@ -259,14 +260,15 @@ When a device has all 3 aforementioned fields filled in, the driver may
 rely on kernel's default implementation of setting and querying keycode
 mappings.
 
-1.7 dev->getkeycode() and dev->setkeycode()
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+dev->getkeycode() and dev->setkeycode()
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 getkeycode() and setkeycode() callbacks allow drivers to override default
 keycode/keycodesize/keycodemax mapping mechanism provided by input core
 and implement sparse keycode maps.
 
-1.8 Key autorepeat
-~~~~~~~~~~~~~~~~~~
+Key autorepeat
+~~~~~~~~~~~~~~
 
 ... is simple. It is handled by the input.c module. Hardware autorepeat is
 not used, because it's not present in many devices and even where it is
@@ -274,29 +276,30 @@ present, it is broken sometimes (at keyboards: Toshiba notebooks). To enable
 autorepeat for your device, just set EV_REP in dev->evbit. All will be
 handled by the input system.
 
-1.9 Other event types, handling output events
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Other event types, handling output events
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The other event types up to now are:
 
-EV_LED - used for the keyboard LEDs.
-EV_SND - used for keyboard beeps.
+- EV_LED - used for the keyboard LEDs.
+- EV_SND - used for keyboard beeps.
 
 They are very similar to for example key events, but they go in the other
 direction - from the system to the input device driver. If your input device
 driver can handle these events, it has to set the respective bits in evbit,
-*and* also the callback routine:
+*and* also the callback routine::
 
-	button_dev->event = button_event;
+    button_dev->event = button_event;
 
-int button_event(struct input_dev *dev, unsigned int type, unsigned int code, int value);
-{
-	if (type == EV_SND && code == SND_BELL) {
-		outb(value, BUTTON_BELL);
-		return 0;
-	}
-	return -1;
-}
+    int button_event(struct input_dev *dev, unsigned int type,
+		     unsigned int code, int value)
+    {
+	    if (type == EV_SND && code == SND_BELL) {
+		    outb(value, BUTTON_BELL);
+		    return 0;
+	    }
+	    return -1;
+    }
 
 This callback routine can be called from an interrupt or a BH (although that
 isn't a rule), and thus must not sleep, and must not take too long to finish.
-- 
2.9.3

[PATCH v2 18/37] docs: input/joystick-api: convert it to ReST format

[Mauro Carvalho Chehab]

This file require some adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/joystick-api.txt | 138 +++++++++++++++++++----------------
 1 file changed, 75 insertions(+), 63 deletions(-)

diff --git a/Documentation/input/joystick-api.txt b/Documentation/input/joystick-api.txt
index 943b18eac918..9b9d26833086 100644
--- a/Documentation/input/joystick-api.txt
+++ b/Documentation/input/joystick-api.txt
@@ -1,12 +1,11 @@
-		      Joystick API Documentation                -*-Text-*-
+==========================
+Joystick API Documentation
+==========================
 
-		        Ragnar Hojland Espinosa
-			  <ragnar@macula.net>
+:Author: Ragnar Hojland Espinosa <ragnar@macula.net> - 7 Aug 1998
 
-			      7 Aug 1998
-
-1. Initialization
-~~~~~~~~~~~~~~~~~
+Initialization
+==============
 
 Open the joystick device following the usual semantics (that is, with open).
 Since the driver now reports events instead of polling for changes,
@@ -14,18 +13,20 @@ 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
 joystick.
 
-By default, the device is opened in blocking mode.
+By default, the device is opened in blocking mode::
 
 	int fd = open ("/dev/input/js0", O_RDONLY);
 
 
-2. Event Reading
-~~~~~~~~~~~~~~~~
+Event Reading
+=============
+
+::
 
 	struct js_event e;
 	read (fd, &e, sizeof(e));
 
-where js_event is defined as
+where js_event is defined as::
 
 	struct js_event {
 		__u32 time;     /* event timestamp in milliseconds */
@@ -38,10 +39,10 @@ If the read is successful, it will return sizeof(e), unless you wanted to read
 more than one event per read as described in section 3.1.
 
 
-2.1 js_event.type
-~~~~~~~~~~~~~~~~~
+js_event.type
+-------------
 
-The possible values of ``type'' are
+The possible values of ``type`` are::
 
 	#define JS_EVENT_BUTTON         0x01    /* button pressed/released */
 	#define JS_EVENT_AXIS           0x02    /* joystick moved */
@@ -49,47 +50,50 @@ The possible values of ``type'' are
 
 As mentioned above, the driver will issue synthetic JS_EVENT_INIT ORed
 events on open. That is, if it's issuing a INIT BUTTON event, the
-current type value will be
+current type value will be::
 
 	int type = JS_EVENT_BUTTON | JS_EVENT_INIT;	/* 0x81 */
 
 If you choose not to differentiate between synthetic or real events
-you can turn off the JS_EVENT_INIT bits
+you can turn off the JS_EVENT_INIT bits::
 
 	type &= ~JS_EVENT_INIT;				/* 0x01 */
 
 
-2.2 js_event.number
-~~~~~~~~~~~~~~~~~~~
+js_event.number
+---------------
 
-The values of ``number'' correspond to the axis or button that
+The values of ``number`` correspond to the axis or button that
 generated the event. Note that they carry separate numeration (that
 is, you have both an axis 0 and a button 0). Generally,
 
-			number
+        =============== =======
+	Axis		number
+        =============== =======
 	1st Axis X	0
 	1st Axis Y	1
 	2nd Axis X	2
 	2nd Axis Y	3
 	...and so on
+        =============== =======
 
 Hats vary from one joystick type to another. Some can be moved in 8
 directions, some only in 4, The driver, however, always reports a hat as two
 independent axis, even if the hardware doesn't allow independent movement.
 
 
-2.3 js_event.value
-~~~~~~~~~~~~~~~~~~
+js_event.value
+--------------
 
-For an axis, ``value'' is a signed integer between -32767 and +32767
+For an axis, ``value`` is a signed integer between -32767 and +32767
 representing the position of the joystick along that axis. If you
-don't read a 0 when the joystick is `dead', or if it doesn't span the
+don't read a 0 when the joystick is ``dead``, or if it doesn't span the
 full range, you should recalibrate it (with, for example, jscal).
 
-For a button, ``value'' for a press button event is 1 and for a release
+For a button, ``value`` for a press button event is 1 and for a release
 button event is 0.
 
-Though this
+Though this::
 
 	if (js_event.type == JS_EVENT_BUTTON) {
 		buttons_state ^= (1 << js_event.number);
@@ -97,6 +101,8 @@ Though this
 
 may work well if you handle JS_EVENT_INIT events separately,
 
+::
+
 	if ((js_event.type & ~JS_EVENT_INIT) == JS_EVENT_BUTTON) {
 		if (js_event.value)
 			buttons_state |= (1 << js_event.number);
@@ -109,17 +115,17 @@ have to write a separate handler for JS_EVENT_INIT events in the first
 snippet, this ends up being shorter.
 
 
-2.4 js_event.time
-~~~~~~~~~~~~~~~~~
+js_event.time
+-------------
 
-The time an event was generated is stored in ``js_event.time''. It's a time
+The time an event was generated is stored in ``js_event.time``. It's a time
 in milliseconds since ... well, since sometime in the past.  This eases the
 task of detecting double clicks, figuring out if movement of axis and button
 presses happened at the same time, and similar.
 
 
-3. Reading
-~~~~~~~~~~
+Reading
+=======
 
 If you open the device in blocking mode, a read will block (that is,
 wait) forever until an event is generated and effectively read. There
@@ -133,8 +139,8 @@ admittedly, a long time;)
 	b) open the device in non-blocking mode (O_NONBLOCK)
 
 
-3.1 O_NONBLOCK
-~~~~~~~~~~~~~~
+O_NONBLOCK
+----------
 
 If read returns -1 when reading in O_NONBLOCK mode, this isn't
 necessarily a "real" error (check errno(3)); it can just mean there
@@ -143,6 +149,8 @@ all events on the queue (that is, until you get a -1).
 
 For example,
 
+::
+
 	while (1) {
 		while (read (fd, &e, sizeof(e)) > 0) {
 			process_event (e);
@@ -171,14 +179,17 @@ the driver will switch to startup mode and next time you read it,
 synthetic events (JS_EVENT_INIT) will be generated to inform you of
 the actual state of the joystick.
 
-[As for version 1.2.8, the queue is circular and able to hold 64
+
+.. note::
+
+ As for 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.]
+ joystick.h and recompiling the driver.
 
 
 In the above code, you might as well want to read more than one event
 at a time using the typical read(2) functionality. For that, you would
-replace the read above with something like
+replace the read above with something like::
 
 	struct js_event mybuffer[0xff];
 	int i = read (fd, mybuffer, sizeof(mybuffer));
@@ -189,10 +200,10 @@ sizeof(js_event)  Again, if the buffer was full, it's a good idea to
 process the events and keep reading it until you empty the driver queue.
 
 
-4. IOCTLs
-~~~~~~~~~
+IOCTLs
+======
 
-The joystick driver defines the following ioctl(2) operations.
+The joystick driver defines the following ioctl(2) operations::
 
 				/* function			3rd arg  */
 	#define JSIOCGAXES	/* get number of axes		char	 */
@@ -202,31 +213,31 @@ The joystick driver defines the following ioctl(2) operations.
 	#define JSIOCSCORR	/* set correction values	&js_corr */
 	#define JSIOCGCORR	/* get correction values	&js_corr */
 
-For example, to read the number of axes
+For example, to read the number of axes::
 
 	char number_of_axes;
 	ioctl (fd, JSIOCGAXES, &number_of_axes);
 
 
-4.1 JSIOGCVERSION
-~~~~~~~~~~~~~~~~~
+JSIOGCVERSION
+-------------
 
 JSIOGCVERSION is a good way to check in run-time whether the running
 driver is 1.0+ and supports the event interface. If it is not, the
 IOCTL will fail. For a compile-time decision, you can test the
-JS_VERSION symbol
+JS_VERSION symbol::
 
 	#ifdef JS_VERSION
 	#if JS_VERSION > 0xsomething
 
 
-4.2 JSIOCGNAME
-~~~~~~~~~~~~~~
+JSIOCGNAME
+----------
 
 JSIOCGNAME(len) allows you to get the name string of the joystick - the same
 as is being printed at boot time. The 'len' argument is the length of the
 buffer provided by the application asking for the name. It is used to avoid
-possible overrun should the name be too long.
+possible overrun should the name be too long::
 
 	char name[128];
 	if (ioctl(fd, JSIOCGNAME(sizeof(name)), name) < 0)
@@ -234,8 +245,8 @@ possible overrun should the name be too long.
 	printf("Name: %s\n", name);
 
 
-4.3 JSIOC[SG]CORR
-~~~~~~~~~~~~~~~~~
+JSIOC[SG]CORR
+-------------
 
 For usage on JSIOC[SG]CORR I suggest you to look into jscal.c  They are
 not needed in a normal program, only in joystick calibration software
@@ -246,7 +257,7 @@ warning in following releases of the driver.
 Both JSIOCSCORR and JSIOCGCORR expect &js_corr to be able to hold
 information for all axis. That is, struct js_corr corr[MAX_AXIS];
 
-struct js_corr is defined as
+struct js_corr is defined as::
 
 	struct js_corr {
 		__s32 coef[8];
@@ -254,17 +265,17 @@ struct js_corr is defined as
 		__u16 type;
 	};
 
-and ``type''
+and ``type``::
 
 	#define JS_CORR_NONE            0x00    /* returns raw values */
 	#define JS_CORR_BROKEN          0x01    /* broken line */
 
 
-5. Backward compatibility
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Backward compatibility
+======================
 
 The 0.x joystick driver API is quite limited and its usage is deprecated.
-The driver offers backward compatibility, though. Here's a quick summary:
+The driver offers backward compatibility, though. Here's a quick summary::
 
 	struct JS_DATA_TYPE js;
 	while (1) {
@@ -275,7 +286,7 @@ The driver offers backward compatibility, though. Here's a quick summary:
 	}
 
 As you can figure out from the example, the read returns immediately,
-with the actual state of the joystick.
+with the actual state of the joystick::
 
 	struct JS_DATA_TYPE {
 		int buttons;    /* immediate button state */
@@ -283,12 +294,14 @@ with the actual state of the joystick.
 		int y;          /* immediate y axis value */
 	};
 
-and JS_RETURN is defined as
+and JS_RETURN is defined as::
 
 	#define JS_RETURN       sizeof(struct JS_DATA_TYPE)
 
 To test the state of the buttons,
 
+::
+
 	first_button_state  = js.buttons & 1;
 	second_button_state = js.buttons & 2;
 
@@ -302,13 +315,12 @@ called Multisystem joysticks in this driver), under /dev/djsX. This driver
 doesn't try to be compatible with that interface.
 
 
-6. Final Notes
-~~~~~~~~~~~~~~
+Final Notes
+===========
 
-____/|	Comments, additions, and specially corrections are welcome.
-\ o.O|	Documentation valid for at least version 1.2.8 of the joystick
- =(_)=	driver and as usual, the ultimate source for documentation is
-   U	to "Use The Source Luke" or, at your convenience, Vojtech ;)
+::
 
-					- Ragnar
-EOF
+  ____/|	Comments, additions, and specially corrections are welcome.
+  \ o.O|	Documentation valid for at least version 1.2.8 of the joystick
+   =(_)=	driver and as usual, the ultimate source for documentation is
+     U		to "Use The Source Luke" or, at your convenience, Vojtech ;)
-- 
2.9.3

[PATCH v2 19/37] docs: input/joystick: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/joystick.txt | 541 +++++++++++++++++++++------------------
 1 file changed, 293 insertions(+), 248 deletions(-)

diff --git a/Documentation/input/joystick.txt b/Documentation/input/joystick.txt
index 8d027dc86c1f..202f5a090675 100644
--- a/Documentation/input/joystick.txt
+++ b/Documentation/input/joystick.txt
@@ -1,271 +1,291 @@
-		       Linux Joystick driver v2.0.0
-	       (c) 1996-2000 Vojtech Pavlik <vojtech@ucw.cz>
-			     Sponsored by SuSE
-----------------------------------------------------------------------------
-
-0. Disclaimer
-~~~~~~~~~~~~~
-  This program is free software; you can redistribute it and/or modify it
+.. 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
+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
+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
+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
+For your convenience, the GNU General Public License version 2 is included
 in the package: See the file COPYING.
 
-1. Intro
-~~~~~~~~
-  The joystick driver for Linux provides support for a variety of joysticks
+Intro
+=====
+
+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
+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:
+The input project website is at:
 
 	http://atrey.karlin.mff.cuni.cz/~vojtech/input/
 
-  There is also a mailing list for the driver at:
+There is also a mailing list for the driver at:
 
 	listproc@atrey.karlin.mff.cuni.cz
 
 send "subscribe linux-joystick Your Name" to subscribe to it.
 
-2. Usage
-~~~~~~~~
-  For basic usage you just choose the right options in kernel config and
+Usage
+=====
+
+For basic usage you just choose the right options in kernel config and
 you should be set.
 
-2.1 inpututils
-~~~~~~~~~~~~~~
+inpututils
+----------
+
 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.
 
-2.2 Device nodes
-~~~~~~~~~~~~~~~~
+Device nodes
+------------
+
 For applications to be able to use the joysticks,
-you'll have to manually create these nodes in /dev:
+you'll have to manually create these nodes in /dev::
 
-cd /dev
-rm js*
-mkdir input
-mknod input/js0 c 13 0
-mknod input/js1 c 13 1
-mknod input/js2 c 13 2
-mknod input/js3 c 13 3
-ln -s input/js0 js0
-ln -s input/js1 js1
-ln -s input/js2 js2
-ln -s input/js3 js3
+    cd /dev
+    rm js*
+    mkdir input
+    mknod input/js0 c 13 0
+    mknod input/js1 c 13 1
+    mknod input/js2 c 13 2
+    mknod input/js3 c 13 3
+    ln -s input/js0 js0
+    ln -s input/js1 js1
+    ln -s input/js2 js2
+    ln -s input/js3 js3
 
-For testing with inpututils it's also convenient to create these:
+For testing with inpututils it's also convenient to create these::
 
-mknod input/event0 c 13 64
-mknod input/event1 c 13 65
-mknod input/event2 c 13 66
-mknod input/event3 c 13 67
+    mknod input/event0 c 13 64
+    mknod input/event1 c 13 65
+    mknod input/event2 c 13 66
+    mknod input/event3 c 13 67
 
-2.4 Modules needed 
-~~~~~~~~~~~~~~~~~~
-  For all joystick drivers to function, you'll need the userland interface
-module in kernel, either loaded or compiled in:
+Modules needed
+--------------
+
+For all joystick drivers to function, you'll need the userland interface
+module in kernel, either loaded or compiled in::
 
 	modprobe joydev
 
-  For gameport joysticks, you'll have to load the gameport driver as well;
+For gameport joysticks, you'll have to load the gameport driver as well::
 
 	modprobe ns558
 
-  And for serial port joysticks, you'll need the serial input line
-discipline module loaded and the inputattach utility started:
+And for serial port joysticks, you'll need the serial input line
+discipline module loaded and the inputattach utility started::
 
 	modprobe serport
 	inputattach -xxx /dev/tts/X &
 
-  In addition to that, you'll need the joystick driver module itself, most
-usually you'll have an analog joystick:
+In addition to that, you'll need the joystick driver module itself, most
+usually you'll have an analog joystick::
 
 	modprobe analog
-	
-  For automatic module loading, something like this might work - tailor to
-your needs:
+
+For automatic module loading, something like this might work - tailor to
+your needs::
 
 	alias tty-ldisc-2 serport
 	alias char-major-13 input
 	above input joydev ns558 analog
 	options analog map=gamepad,none,2btn
 
-2.5 Verifying that it works
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  For testing the joystick driver functionality, there is the jstest
-program in the utilities package. You run it by typing:
+Verifying that it works
+-----------------------
+
+For testing the joystick driver functionality, there is the jstest
+program in the utilities package. You run it by typing::
 
 	jstest /dev/input/js0
 
-  And it should show a line with the joystick values, which update as you
+And it should show a line with the joystick values, which update as you
 move the stick, and press its buttons. The axes should all be zero when the
 joystick is in the center position. They should not jitter by themselves to
 other close values, and they also should be steady in any other position of
 the stick. They should have the full range from -32767 to 32767. If all this
 is met, then it's all fine, and you can play the games. :)
 
-  If it's not, then there might be a problem. Try to calibrate the joystick,
+If it's not, then there might be a problem. Try to calibrate the joystick,
 and if it still doesn't work, read the drivers section of this file, the
 troubleshooting section, and the FAQ.
 
-2.6. Calibration
-~~~~~~~~~~~~~~~~
-  For most joysticks you won't need any manual calibration, since the
+Calibration
+-----------
+
+For most joysticks you won't need any manual calibration, since the
 joystick should be autocalibrated by the driver automagically. However, with
 some analog joysticks, that either do not use linear resistors, or if you
-want better precision, you can use the jscal program
+want better precision, you can use the jscal program::
 
 	jscal -c /dev/input/js0
 
- included in the joystick package to set better correction coefficients than
+included in the joystick package to set better correction coefficients than
 what the driver would choose itself.
 
-  After calibrating the joystick you can verify if you like the new
+After calibrating the joystick you can verify if you like the new
 calibration using the jstest command, and if you do, you then can save the
-correction coefficients into a file
+correction coefficients into a file::
 
 	jscal -p /dev/input/js0 > /etc/joystick.cal
 
-  And add a line to your rc script executing that file
+And add a line to your rc script executing that file::
 
 	source /etc/joystick.cal
 
-  This way, after the next reboot your joystick will remain calibrated. You
-can also add the jscal -p line to your shutdown script.
+This way, after the next reboot your joystick will remain calibrated. You
+can also add the ``jscal -p`` line to your shutdown script.
 
 
-3. HW specific driver information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+HW specific driver information
+==============================
+
 In this section each of the separate hardware specific drivers is described.
 
-3.1 Analog joysticks
-~~~~~~~~~~~~~~~~~~~~
-  The analog.c uses the standard analog inputs of the gameport, and thus
+Analog joysticks
+----------------
+
+The analog.c uses the standard analog inputs of the gameport, and thus
 supports all standard joysticks and gamepads. It uses a very advanced
 routine for this, allowing for data precision that can't be found on any
 other system.
 
-  It also supports extensions like additional hats and buttons compatible
+It also supports extensions like additional hats and buttons compatible
 with CH Flightstick Pro, ThrustMaster FCS or 6 and 8 button gamepads. Saitek
 Cyborg 'digital' joysticks are also supported by this driver, because
 they're basically souped up CHF sticks.
 
-  However the only types that can be autodetected are:
+However the only types that can be autodetected are:
 
 * 2-axis, 4-button joystick
 * 3-axis, 4-button joystick
 * 4-axis, 4-button joystick
 * Saitek Cyborg 'digital' joysticks
 
-  For other joystick types (more/less axes, hats, and buttons) support
+For other joystick types (more/less axes, hats, and buttons) support
 you'll need to specify the types either on the kernel command line or on the
 module command line, when inserting analog into the kernel. The
-parameters are:
+parameters are::
 
 	analog.map=<type1>,<type2>,<type3>,....
 
-  'type' is type of the joystick from the table below, defining joysticks
+'type' is type of the joystick from the table below, defining joysticks
 present on gameports in the system, starting with gameport0, second 'type'
 entry defining joystick on gameport1 and so on.
 
-	Type     | Meaning
-	-----------------------------------
-	none     | No analog joystick on that port
-	auto     | Autodetect joystick
-	2btn     | 2-button n-axis joystick
-	y-joy    | Two 2-button 2-axis joysticks on an Y-cable
-	y-pad    | Two 2-button 2-axis gamepads on an Y-cable
-	fcs      | Thrustmaster FCS compatible joystick
-	chf      | Joystick with a CH Flightstick compatible hat
-	fullchf  | CH Flightstick compatible with two hats and 6 buttons
-	gamepad  | 4/6-button n-axis gamepad
-	gamepad8 | 8-button 2-axis gamepad
+	========= =====================================================
+	Type      Meaning
+	========= =====================================================
+	none      No analog joystick on that port
+	auto      Autodetect joystick
+	2btn      2-button n-axis joystick
+	y-joy     Two 2-button 2-axis joysticks on an Y-cable
+	y-pad     Two 2-button 2-axis gamepads on an Y-cable
+	fcs       Thrustmaster FCS compatible joystick
+	chf       Joystick with a CH Flightstick compatible hat
+	fullchf   CH Flightstick compatible with two hats and 6 buttons
+	gamepad   4/6-button n-axis gamepad
+	gamepad8  8-button 2-axis gamepad
+	========= =====================================================
 
-  In case your joystick doesn't fit in any of the above categories, you can
+In case your joystick doesn't fit in any of the above categories, you can
 specify the type as a number by combining the bits in the table below. This
 is not recommended unless you really know what are you doing. It's not
 dangerous, but not simple either.
 
-	Bit | Meaning
-	--------------------------
-	 0  | Axis X1
-	 1  | Axis Y1
-	 2  | Axis X2
-	 3  | Axis Y2
-	 4  | Button A
-	 5  | Button B
-	 6  | Button C
-	 7  | Button D
-	 8  | CHF Buttons X and Y
-	 9  | CHF Hat 1
-	10  | CHF Hat 2
-	11  | FCS Hat
-	12  | Pad Button X
-	13  | Pad Button Y
-	14  | Pad Button U
-	15  | Pad Button V
-	16  | Saitek F1-F4 Buttons
-	17  | Saitek Digital Mode
-	19  | GamePad
-	20  | Joy2 Axis X1
-	21  | Joy2 Axis Y1
-	22  | Joy2 Axis X2
-	23  | Joy2 Axis Y2
-	24  | Joy2 Button A
-	25  | Joy2 Button B
-	26  | Joy2 Button C
-	27  | Joy2 Button D
-	31  | Joy2 GamePad
+	==== =========================
+	Bit  Meaning
+	==== =========================
+	 0   Axis X1
+	 1   Axis Y1
+	 2   Axis X2
+	 3   Axis Y2
+	 4   Button A
+	 5   Button B
+	 6   Button C
+	 7   Button D
+	 8   CHF Buttons X and Y
+	 9   CHF Hat 1
+	10   CHF Hat 2
+	11   FCS Hat
+	12   Pad Button X
+	13   Pad Button Y
+	14   Pad Button U
+	15   Pad Button V
+	16   Saitek F1-F4 Buttons
+	17   Saitek Digital Mode
+	19   GamePad
+	20   Joy2 Axis X1
+	21   Joy2 Axis Y1
+	22   Joy2 Axis X2
+	23   Joy2 Axis Y2
+	24   Joy2 Button A
+	25   Joy2 Button B
+	26   Joy2 Button C
+	27   Joy2 Button D
+	31   Joy2 GamePad
+	==== =========================
 
-3.2 Microsoft SideWinder joysticks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c
+Microsoft SideWinder joysticks
+------------------------------
+
+Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c
 module. All currently supported joysticks:
 
 * Microsoft SideWinder 3D Pro
 * Microsoft SideWinder Force Feedback Pro
 * Microsoft SideWinder Force Feedback Wheel
-* Microsoft SideWinder FreeStyle Pro 
+* Microsoft SideWinder FreeStyle Pro
 * Microsoft SideWinder GamePad (up to four, chained)
-* Microsoft SideWinder Precision Pro 
-* Microsoft SideWinder Precision Pro USB 
+* Microsoft SideWinder Precision Pro
+* Microsoft SideWinder Precision Pro USB
 
-  are autodetected, and thus no module parameters are needed.
+are autodetected, and thus no module parameters are needed.
 
-  There is one caveat with the 3D Pro. There are 9 buttons reported,
+There is one caveat with the 3D Pro. There are 9 buttons reported,
 although the joystick has only 8. The 9th button is the mode switch on the
 rear side of the joystick. However, moving it, you'll reset the joystick,
 and make it unresponsive for about a one third of a second. Furthermore, the
 joystick will also re-center itself, taking the position it was in during
 this time as a new center position. Use it if you want, but think first.
 
-  The SideWinder Standard is not a digital joystick, and thus is supported
-by the analog driver described above. 
+The SideWinder Standard is not a digital joystick, and thus is supported
+by the analog driver described above.
 
-3.3 Logitech ADI devices
-~~~~~~~~~~~~~~~~~~~~~~~~
-  Logitech ADI protocol is supported by the adi.c module. It should support
+Logitech ADI devices
+--------------------
+
+Logitech ADI protocol is supported by the adi.c module. It should support
 any Logitech device using this protocol. This includes, but is not limited
 to:
 
@@ -279,20 +299,21 @@ to:
 * Logitech WingMan GamePad Extreme
 * Logitech WingMan Extreme Digital 3D
 
-  ADI devices are autodetected, and the driver supports up to two (any
+ADI devices are autodetected, and the driver supports up to two (any
 combination of) devices on a single gameport, using an Y-cable or chained
 together.
 
-  Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan
+Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan
 Extreme and Logitech WingMan ThunderPad are not digital joysticks and are
 handled by the analog driver described above. Logitech WingMan Warrior and
 Logitech Magellan are supported by serial drivers described below.  Logitech
 WingMan Force and Logitech WingMan Formula Force are supported by the
 I-Force driver described below. Logitech CyberMan is not supported yet.
 
-3.4 Gravis GrIP
-~~~~~~~~~~~~~~~
-  Gravis GrIP protocol is supported by the grip.c module. It currently
+Gravis GrIP
+-----------
+
+Gravis GrIP protocol is supported by the grip.c module. It currently
 supports:
 
 * Gravis GamePad Pro
@@ -300,7 +321,7 @@ supports:
 * Gravis Xterminator
 * Gravis Xterminator DualControl
 
-  All these devices are autodetected, and you can even use any combination
+All these devices are autodetected, and you can even use any combination
 of up to two of these pads either chained together or using an Y-cable on a
 single gameport.
 
@@ -308,9 +329,10 @@ GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is
 supported by the stinger driver. Other Gravis joysticks are supported by the
 analog driver.
 
-3.5 FPGaming A3D and MadCatz A3D
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The Assassin 3D protocol created by FPGaming, is used both by FPGaming
+FPGaming A3D and MadCatz A3D
+----------------------------
+
+The Assassin 3D protocol created by FPGaming, is used both by FPGaming
 themselves and is licensed to MadCatz. A3D devices are supported by the
 a3d.c module. It currently supports:
 
@@ -318,125 +340,139 @@ a3d.c module. It currently supports:
 * MadCatz Panther
 * MadCatz Panther XL
 
-  All these devices are autodetected. Because the Assassin 3D and the Panther
+All these devices are autodetected. Because the Assassin 3D and the Panther
 allow connecting analog joysticks to them, you'll need to load the analog
 driver as well to handle the attached joysticks.
 
-  The trackball should work with USB mousedev module as a normal mouse. See
+The trackball should work with USB mousedev module as a normal mouse. See
 the USB documentation for how to setup an USB mouse.
 
-3.6 ThrustMaster DirectConnect (BSP)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The TM DirectConnect (BSP) protocol is supported by the tmdc.c
+ThrustMaster DirectConnect (BSP)
+--------------------------------
+
+The TM DirectConnect (BSP) protocol is supported by the tmdc.c
 module. This includes, but is not limited to:
 
 * ThrustMaster Millennium 3D Interceptor
 * ThrustMaster 3D Rage Pad
 * ThrustMaster Fusion Digital Game Pad
 
-  Devices not directly supported, but hopefully working are:
+Devices not directly supported, but hopefully working are:
 
 * ThrustMaster FragMaster
 * ThrustMaster Attack Throttle
 
-  If you have one of these, contact me.
+If you have one of these, contact me.
 
-  TMDC devices are autodetected, and thus no parameters to the module
+TMDC devices are autodetected, and thus no parameters to the module
 are needed. Up to two TMDC devices can be connected to one gameport, using
 an Y-cable.
 
-3.7 Creative Labs Blaster
-~~~~~~~~~~~~~~~~~~~~~~~~~
-  The Blaster protocol is supported by the cobra.c module. It supports only
+Creative Labs Blaster
+---------------------
+
+The Blaster protocol is supported by the cobra.c module. It supports only
 the:
 
 * Creative Blaster GamePad Cobra
 
-  Up to two of these can be used on a single gameport, using an Y-cable.
+Up to two of these can be used on a single gameport, using an Y-cable.
 
-3.8 Genius Digital joysticks 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The Genius digitally communicating joysticks are supported by the gf2k.c
+Genius Digital joysticks
+------------------------
+
+The Genius digitally communicating joysticks are supported by the gf2k.c
 module. This includes:
 
-* Genius Flight2000 F-23 joystick 
-* Genius Flight2000 F-31 joystick 
+* Genius Flight2000 F-23 joystick
+* Genius Flight2000 F-31 joystick
 * Genius G-09D gamepad
 
-  Other Genius digital joysticks are not supported yet, but support can be
+Other Genius digital joysticks are not supported yet, but support can be
 added fairly easily.
 
-3.9 InterAct Digital joysticks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The InterAct digitally communicating joysticks are supported by the
+InterAct Digital joysticks
+--------------------------
+
+The InterAct digitally communicating joysticks are supported by the
 interact.c module. This includes:
 
 * InterAct HammerHead/FX gamepad
-* InterAct ProPad8 gamepad 
+* InterAct ProPad8 gamepad
 
-  Other InterAct digital joysticks are not supported yet, but support can be 
+Other InterAct digital joysticks are not supported yet, but support can be
 added fairly easily.
 
-3.10 PDPI Lightning 4 gamecards
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  PDPI Lightning 4 gamecards are supported by the lightning.c module.
+PDPI Lightning 4 gamecards
+--------------------------
+
+PDPI Lightning 4 gamecards are supported by the lightning.c module.
 Once the module is loaded, the analog driver can be used to handle the
 joysticks. Digitally communicating joystick will work only on port 0, while
 using Y-cables, you can connect up to 8 analog joysticks to a single L4
 card, 16 in case you have two in your system.
 
-3.11 Trident 4DWave / Aureal Vortex
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipsets
+Trident 4DWave / Aureal Vortex
+------------------------------
+
+Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipsets
 provide an "Enhanced Game Port" mode where the soundcard handles polling the
 joystick.  This mode is supported by the pcigame.c module. Once loaded the
 analog driver can use the enhanced features of these gameports..
 
-3.13 Crystal SoundFusion
-~~~~~~~~~~~~~~~~~~~~~~~~
-  Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game
+Crystal SoundFusion
+-------------------
+
+Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game
 Port", much like the 4DWave or Vortex above. This, and also the normal mode
 for the port of the SoundFusion is supported by the cs461x.c module.
 
-3.14 SoundBlaster Live!
-~~~~~~~~~~~~~~~~~~~~~~~~
-  The Live! has a special PCI gameport, which, although it doesn't provide
+SoundBlaster Live!
+------------------
+
+The Live! has a special PCI gameport, which, although it doesn't provide
 any "Enhanced" stuff like 4DWave and friends, is quite a bit faster than
 its ISA counterparts. It also requires special support, hence the
 emu10k1-gp.c module for it instead of the normal ns558.c one.
 
-3.15 SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  These PCI soundcards have specific gameports. They are handled by the
+SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes
+------------------------------------------------------------------------
+
+These PCI soundcards have specific gameports. They are handled by the
 sound drivers themselves. Make sure you select gameport support in the
 joystick menu and sound card support in the sound menu for your appropriate
 card.
 
-3.16 Amiga
-~~~~~~~~~~
-  Amiga joysticks, connected to an Amiga, are supported by the amijoy.c
-driver. Since they can't be autodetected, the driver has a command line.
+Amiga
+-----
+
+Amiga joysticks, connected to an Amiga, are supported by the amijoy.c
+driver. Since they can't be autodetected, the driver has a command line:
 
 	amijoy.map=<a>,<b>
 
-  a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of
+a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of
 the Amiga.
 
-	Value | Joystick type
-	---------------------
-	  0   | None
-	  1   | 1-button digital joystick
+	====== ===========================
+	Value  Joystick type
+	====== ===========================
+	  0    None
+	  1    1-button digital joystick
+	====== ===========================
 
-  No more joystick types are supported now, but that should change in the
+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.
 
-3.17 Game console and 8-bit pads and joysticks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-See joystick-parport.txt for more info.
+Game console and 8-bit pads and joysticks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-3.18 SpaceTec/LabTec devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  SpaceTec serial devices communicate using the SpaceWare protocol. It is
+See :ref:`joystick-parport` for more info.
+
+SpaceTec/LabTec devices
+-----------------------
+
+SpaceTec serial devices communicate using the SpaceWare protocol. It is
 supported by the spaceorb.c and spaceball.c drivers. The devices currently
 supported by spaceorb.c are:
 
@@ -447,43 +483,47 @@ Devices currently supported by spaceball.c are:
 
 * SpaceTec SpaceBall 4000 FLX
 
-  In addition to having the spaceorb/spaceball and serport modules in the
+In addition to having the spaceorb/spaceball and serport modules in the
 kernel, you also need to attach a serial port to it. to do that, run the
-inputattach program:
+inputattach program::
 
 	inputattach --spaceorb /dev/tts/x &
-or
+
+or::
+
 	inputattach --spaceball /dev/tts/x &
 
 where /dev/tts/x is the serial port which the device is connected to. After
 doing this, the device will be reported and will start working.
 
-  There is one caveat with the SpaceOrb. The button #6, the on the bottom
+There is one caveat with the SpaceOrb. The button #6, the on the bottom
 side of the orb, although reported as an ordinary button, causes internal
 recentering of the spaceorb, moving the zero point to the position in which
 the ball is at the moment of pressing the button. So, think first before
 you bind it to some other function.
 
-SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet. 
+SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet.
 
-3.19 Logitech SWIFT devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The SWIFT serial protocol is supported by the warrior.c module. It
+Logitech SWIFT devices
+----------------------
+
+The SWIFT serial protocol is supported by the warrior.c module. It
 currently supports only the:
 
 * Logitech WingMan Warrior
 
 but in the future, Logitech CyberMan (the original one, not CM2) could be
 supported as well. To use the module, you need to run inputattach after you
-insert/compile the module into your kernel:
+insert/compile the module into your kernel::
 
 	inputattach --warrior /dev/tts/x &
 
 /dev/tts/x is the serial port your Warrior is attached to.
 
-3.20 Magellan / Space Mouse
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space
+Magellan / Space Mouse
+----------------------
+
+The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space
 Systems), for many other companies (Logitech, HP, ...) is supported by the
 joy-magellan module. It currently supports only the:
 
@@ -492,94 +532,99 @@ joy-magellan module. It currently supports only the:
 
 models, the additional buttons on the 'Plus' versions are not supported yet.
 
-  To use it, you need to attach the serial port to the driver using the
+To use it, you need to attach the serial port to the driver using the::
 
 	inputattach --magellan /dev/tts/x &
 
 command. After that the Magellan will be detected, initialized, will beep,
 and the /dev/input/jsX device should become usable.
 
-3.21 I-Force devices 
-~~~~~~~~~~~~~~~~~~~~
-  All I-Force devices are supported by the iforce module. This includes:
+I-Force devices
+---------------
+
+All I-Force devices are supported by the iforce module. This includes:
 
 * AVB Mag Turbo Force
 * AVB Top Shot Pegasus
 * AVB Top Shot Force Feedback Racing Wheel
 * Logitech WingMan Force
-* Logitech WingMan Force Wheel 
+* Logitech WingMan Force Wheel
 * Guillemot Race Leader Force Feedback
 * Guillemot Force Feedback Racing Wheel
 * Thrustmaster Motor Sport GT
 
-  To use it, you need to attach the serial port to the driver using the
+To use it, you need to attach the serial port to the driver using the::
 
 	inputattach --iforce /dev/tts/x &
 
 command. After that the I-Force device will be detected, and the
 /dev/input/jsX device should become usable.
 
-  In case you're using the device via the USB port, the inputattach command
+In case you're using the device via the USB port, the inputattach command
 isn't needed.
 
-  The I-Force driver now supports force feedback via the event interface.
+The I-Force driver now supports force feedback via the event interface.
 
-  Please note that Logitech WingMan *3D devices are _not_ supported by this
+Please note that Logitech WingMan 3D devices are _not_ supported by this
 module, rather by hid. Force feedback is not supported for those devices.
 Logitech gamepads are also hid devices.
 
-3.22 Gravis Stinger gamepad 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The Gravis Stinger serial port gamepad, designed for use with laptop
+Gravis Stinger gamepad
+----------------------
+
+The Gravis Stinger serial port gamepad, designed for use with laptop
 computers, is supported by the stinger.c module. To use it, attach the
-serial port to the driver using:
+serial port to the driver using::
 
-        inputattach --stinger /dev/tty/x &
+	inputattach --stinger /dev/tty/x &
 
 where x is the number of the serial port.
 
-4. Troubleshooting
-~~~~~~~~~~~~~~~~~~
-  There is quite a high probability that you run into some problems. For
+Troubleshooting
+===============
+
+There is quite a high probability that you run into some problems. For
 testing whether the driver works, if in doubt, use the jstest utility in
 some of its modes. The most useful modes are "normal" - for the 1.x
-interface, and "old" for the "0.x" interface. You run it by typing:
+interface, and "old" for the "0.x" interface. You run it by typing::
 
 	jstest --normal /dev/input/js0
 	jstest --old    /dev/input/js0
 
-  Additionally you can do a test with the evtest utility:
+Additionally you can do a test with the evtest utility::
 
 	evtest /dev/input/event0
 
-  Oh, and read the FAQ! :)
+Oh, and read the FAQ! :)
 
-5. FAQ
-~~~~~~
-Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the
-   cause?
-A: The device files don't exist. Create them (see section 2.2).
+FAQ
+===
 
-Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick
-   or pad that uses a 9-pin D-type cannon connector to the serial port of my
-   PC?
-A: Yes, it is possible, but it'll burn your serial port or the pad. It
-   won't work, of course.
+:Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the
+    cause?
+:A: The device files don't exist. Create them (see section 2.2).
 
-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.
+:Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick
+    or pad that uses a 9-pin D-type cannon connector to the serial port of my
+    PC?
+:A: Yes, it is possible, but it'll burn your serial port or the pad. It
+    won't work, of course.
 
-6. Programming Interface
-~~~~~~~~~~~~~~~~~~~~~~~~
-  The 1.0 driver uses a new, event based approach to the joystick driver.
+: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.
+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
-- 
2.9.3

[PATCH v2 20/37] docs: input/joystick-parport: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/joystick-parport.txt | 708 ++++++++++++++++---------------
 1 file changed, 370 insertions(+), 338 deletions(-)

diff --git a/Documentation/input/joystick-parport.txt b/Documentation/input/joystick-parport.txt
index 56870c70a796..0aa0fb17bf48 100644
--- a/Documentation/input/joystick-parport.txt
+++ b/Documentation/input/joystick-parport.txt
@@ -1,333 +1,349 @@
-		    Linux Joystick parport drivers v2.0
-	       (c) 1998-2000 Vojtech Pavlik <vojtech@ucw.cz>
-	       (c) 1998 Andree Borrmann <a.borrmann@tu-bs.de>
-			     Sponsored by SuSE
-----------------------------------------------------------------------------
-
-0. Disclaimer
-~~~~~~~~~~~~~
-  Any information in this file is provided as-is, without any guarantee that
+.. include:: <isonum.txt>
+
+.. _joystick-parport:
+
+===================================
+Linux Joystick parport drivers v2.0
+===================================
+
+:Copyright: |copy| 1998-2000 Vojtech Pavlik <vojtech@ucw.cz>
+:Copyright: |copy| 1998 Andree Borrmann <a.borrmann@tu-bs.de>
+
+
+Sponsored by SuSE
+
+Disclaimer
+==========
+
+Any information in this file is provided as-is, without any guarantee that
 it will be true. So, use it at your own risk. The possible damages that can
 happen include burning your parallel port, and/or the sticks and joystick
 and maybe even more. Like when a lightning kills you it is not our problem.
 
-1. Intro
-~~~~~~~~
-  The joystick parport drivers are used for joysticks and gamepads not
+Intro
+=====
+
+The joystick parport drivers are used for joysticks and gamepads not
 originally designed for PCs and other computers Linux runs on. Because of
 that, PCs usually lack the right ports to connect these devices to. Parallel
 port, because of its ability to change single bits at will, and providing
 both output and input bits is the most suitable port on the PC for
 connecting such devices.
 
-2. Devices supported
-~~~~~~~~~~~~~~~~~~~~
-  Many console and 8-bit computer gamepads and joysticks are supported. The
+Devices supported
+=================
+
+Many console and 8-bit computer gamepads and joysticks are supported. The
 following subsections discuss usage of each.
 
-2.1 NES and SNES
-~~~~~~~~~~~~~~~~
-  The Nintendo Entertainment System and Super Nintendo Entertainment System
+NES and SNES
+------------
+
+The Nintendo Entertainment System and Super Nintendo Entertainment System
 gamepads are widely available, and easy to get. Also, they are quite easy to
 connect to a PC, and don't need much processing speed (108 us for NES and
 165 us for SNES, compared to about 1000 us for PC gamepads) to communicate
 with them.
 
-  All NES and SNES use the same synchronous serial protocol, clocked from
+All NES and SNES use the same synchronous serial protocol, clocked from
 the computer's side (and thus timing insensitive). To allow up to 5 NES
 and/or SNES gamepads and/or SNES mice connected to the parallel port at once,
 the output lines of the parallel port are shared, while one of 5 available
 input lines is assigned to each gamepad.
 
-  This protocol is handled by the gamecon.c driver, so that's the one
+This protocol is handled by the gamecon.c driver, so that's the one
 you'll use for NES, SNES gamepads and SNES mice.
 
-  The main problem with PC parallel ports is that they don't have +5V power
+The main problem with PC parallel ports is that they don't have +5V power
 source on any of their pins. So, if you want a reliable source of power
 for your pads, use either keyboard or joystick port, and make a pass-through
 cable. You can also pull the power directly from the power supply (the red
 wire is +5V).
 
-  If you want to use the parallel port only, you can take the power is from
+If you want to use the parallel port only, you can take the power is from
 some data pin. For most gamepad and parport implementations only one pin is
 needed, and I'd recommend pin 9 for that, the highest data bit. On the other
 hand, if you are not planning to use anything else than NES / SNES on the
-port, anything between and including pin 4 and pin 9 will work.
+port, anything between and including pin 4 and pin 9 will work::
 
-(pin 9) -----> Power
+    (pin 9) -----> Power
 
-  Unfortunately, there are pads that need a lot more of power, and parallel
+Unfortunately, there are pads that need a lot more of power, and parallel
 ports that can't give much current through the data pins. If this is your
 case, you'll need to use diodes (as a prevention of destroying your parallel
-port), and combine the currents of two or more data bits together.
+port), and combine the currents of two or more data bits together::
 
-	   Diodes
-(pin 9) ----|>|-------+------> Power
-		      |
-(pin 8) ----|>|-------+
-		      |
-(pin 7) ----|>|-------+
-		      |
- <and so on>          :
-		      |
-(pin 4) ----|>|-------+
+	      Diodes
+    (pin 9) ----|>|-------+------> Power
+			|
+    (pin 8) ----|>|-------+
+			|
+    (pin 7) ----|>|-------+
+			|
+    <and so on>         :
+			|
+    (pin 4) ----|>|-------+
 
-  Ground is quite easy. On PC's parallel port the ground is on any of the
-pins from pin 18 to pin 25. So use any pin of these you like for the ground.
+Ground is quite easy. On PC's parallel port the ground is on any of the
+pins from pin 18 to pin 25. So use any pin of these you like for the ground::
 
-(pin 18) -----> Ground
+    (pin 18) -----> Ground
 
-  NES and SNES pads have two input bits, Clock and Latch, which drive the
+NES and SNES pads have two input bits, Clock and Latch, which drive the
 serial transfer. These are connected to pins 2 and 3 of the parallel port,
-respectively.
+respectively::
 
-(pin 2) -----> Clock
-(pin 3) -----> Latch
+    (pin 2) -----> Clock
+    (pin 3) -----> Latch
 
-  And the last thing is the NES / SNES data wire. Only that isn't shared and
-each pad needs its own data pin. The parallel port pins are:
+And the last thing is the NES / SNES data wire. Only that isn't shared and
+each pad needs its own data pin. The parallel port pins are::
 
-(pin 10) -----> Pad 1 data
-(pin 11) -----> Pad 2 data
-(pin 12) -----> Pad 3 data
-(pin 13) -----> Pad 4 data
-(pin 15) -----> Pad 5 data
+    (pin 10) -----> Pad 1 data
+    (pin 11) -----> Pad 2 data
+    (pin 12) -----> Pad 3 data
+    (pin 13) -----> Pad 4 data
+    (pin 15) -----> Pad 5 data
 
-  Note that pin 14 is not used, since it is not an input pin on the parallel
+Note that pin 14 is not used, since it is not an input pin on the parallel
 port.
 
-  This is everything you need on the PC's side of the connection, now on to
+This is everything you need on the PC's side of the connection, now on to
 the gamepads side. The NES and SNES have different connectors. Also, there
 are quite a lot of NES clones, and because Nintendo used proprietary
 connectors for their machines, the cloners couldn't and used standard D-Cannon
 connectors. Anyway, if you've got a gamepad, and it has buttons A, B, Turbo
 A, Turbo B, Select and Start, and is connected through 5 wires, then it is
 either a NES or NES clone and will work with this connection. SNES gamepads
-also use 5 wires, but have more buttons. They will work as well, of course.
+also use 5 wires, but have more buttons. They will work as well, of course::
 
-Pinout for NES gamepads                 Pinout for SNES gamepads and mice
+  Pinout for NES gamepads                 Pinout for SNES gamepads and mice
 
-	   +----> Power                   +-----------------------\
-	   |                            7 | o  o  o  o |  x  x  o  | 1
- 5 +---------+  7                         +-----------------------/
-   | x  x  o   \                            |  |  |  |          |
-   | o  o  o  o |                           |  |  |  |          +-> Ground
- 4 +------------+ 1                         |  |  |  +------------> Data
-     |  |  |  |                             |  |  +---------------> Latch
-     |  |  |  +-> Ground                    |  +------------------> Clock
-     |  |  +----> Clock                     +---------------------> Power
-     |  +-------> Latch
-     +----------> Data
+             +----> Power                   +-----------------------\
+             |                            7 | o  o  o  o |  x  x  o  | 1
+   5 +---------+  7                         +-----------------------/
+     | x  x  o   \                            |  |  |  |          |
+     | o  o  o  o |                           |  |  |  |          +-> Ground
+   4 +------------+ 1                         |  |  |  +------------> Data
+       |  |  |  |                             |  |  +---------------> Latch
+       |  |  |  +-> Ground                    |  +------------------> Clock
+       |  |  +----> Clock                     +---------------------> Power
+       |  +-------> Latch
+       +----------> Data
 
-Pinout for NES clone (db9) gamepads     Pinout for NES clone (db15) gamepads
+  Pinout for NES clone (db9) gamepads     Pinout for NES clone (db15) gamepads
 
-	+---------> Clock                    +-----------------> Data
-	| +-------> Latch                    |             +---> Ground
-	| | +-----> Data                     |             |
-	| | |                              ___________________
+        +---------> Clock                    +-----------------> Data
+        | +-------> Latch                    |             +---> Ground
+        | | +-----> Data                     |             |
+        | | |                              ___________________
     _____________                        8 \ o x x x x x x o / 1
   5 \ x o o o x / 1                         \ o x x o x x o /
      \ x o x o /                          15 `~~~~~~~~~~~~~' 9
     9 `~~~~~~~' 6                             |     |     |
-	 |   |                                |     |     +----> Clock
-	 |   +----> Power                     |     +----------> Latch
-	 +--------> Ground                    +----------------> Power
+         |   |                                |     |     +----> Clock
+         |   +----> Power                     |     +----------> Latch
+         +--------> Ground                    +----------------> Power
 
-2.2 Multisystem joysticks
-~~~~~~~~~~~~~~~~~~~~~~~~~
-  In the era of 8-bit machines, there was something like de-facto standard
+Multisystem joysticks
+---------------------
+
+In the era of 8-bit machines, there was something like de-facto standard
 for joystick ports. They were all digital, and all used D-Cannon 9 pin
 connectors (db9). Because of that, a single joystick could be used without
 hassle on Atari (130, 800XE, 800XL, 2600, 7200), Amiga, Commodore C64,
 Amstrad CPC, Sinclair ZX Spectrum and many other machines. That's why these
 joysticks are called "Multisystem".
 
-  Now their pinout:
+Now their pinout::
 
-      +---------> Right
-      | +-------> Left
-      | | +-----> Down
-      | | | +---> Up
-      | | | |
-  _____________
-5 \ x o o o o / 1
-   \ x o x o /
-  9 `~~~~~~~' 6
-       |   |
-       |   +----> Button
-       +--------> Ground
+        +---------> Right
+        | +-------> Left
+        | | +-----> Down
+        | | | +---> Up
+        | | | |
+    _____________
+  5 \ x o o o o / 1
+     \ x o x o /
+    9 `~~~~~~~' 6
+         |   |
+         |   +----> Button
+         +--------> Ground
 
-  However, as time passed, extensions to this standard developed, and these
-were not compatible with each other:
+However, as time passed, extensions to this standard developed, and these
+were not compatible with each other::
 
 
-	Atari 130, 800/XL/XE		   MSX
+          Atari 130, 800/XL/XE                   MSX
 
-					 +-----------> Power
-      +---------> Right                  | +---------> Right
-      | +-------> Left                   | | +-------> Left
-      | | +-----> Down                   | | | +-----> Down
-      | | | +---> Up                     | | | | +---> Up
-      | | | |                            | | | | |
-  _____________                        _____________
-5 \ x o o o o / 1                    5 \ o o o o o / 1
-   \ x o o o /                          \ o o o o /
-  9 `~~~~~~~' 6                        9 `~~~~~~~' 6
-       | | |                              | | | |
-       | | +----> Button                  | | | +----> Button 1
-       | +------> Power                   | | +------> Button 2
-       +--------> Ground                  | +--------> Output 3
-					  +----------> Ground
+                                           +-----------> Power
+        +---------> Right                  | +---------> Right
+        | +-------> Left                   | | +-------> Left
+        | | +-----> Down                   | | | +-----> Down
+        | | | +---> Up                     | | | | +---> Up
+        | | | |                            | | | | |
+    _____________                        _____________
+  5 \ x o o o o / 1                    5 \ o o o o o / 1
+     \ x o o o /                          \ o o o o /
+    9 `~~~~~~~' 6                        9 `~~~~~~~' 6
+         | | |                              | | | |
+         | | +----> Button                  | | | +----> Button 1
+         | +------> Power                   | | +------> Button 2
+         +--------> Ground                  | +--------> Output 3
+                                            +----------> Ground
 
-	Amstrad CPC			   Commodore C64
+          Amstrad CPC                           Commodore C64
 
-					 +-----------> Analog Y
-      +---------> Right                  | +---------> Right
-      | +-------> Left                   | | +-------> Left
-      | | +-----> Down                   | | | +-----> Down
-      | | | +---> Up                     | | | | +---> Up
-      | | | |                            | | | | |
-  _____________                        _____________
-5 \ x o o o o / 1                    5 \ o o o o o / 1
-   \ x o o o /                          \ o o o o /
-  9 `~~~~~~~' 6                        9 `~~~~~~~' 6
-       | | |                              | | | |
-       | | +----> Button 1                | | | +----> Button
-       | +------> Button 2                | | +------> Power
-       +--------> Ground                  | +--------> Ground
-					  +----------> Analog X
+                                           +-----------> Analog Y
+        +---------> Right                  | +---------> Right
+        | +-------> Left                   | | +-------> Left
+        | | +-----> Down                   | | | +-----> Down
+        | | | +---> Up                     | | | | +---> Up
+        | | | |                            | | | | |
+    _____________                        _____________
+  5 \ x o o o o / 1                    5 \ o o o o o / 1
+     \ x o o o /                          \ o o o o /
+    9 `~~~~~~~' 6                        9 `~~~~~~~' 6
+         | | |                              | | | |
+         | | +----> Button 1                | | | +----> Button
+         | +------> Button 2                | | +------> Power
+         +--------> Ground                  | +--------> Ground
+                                            +----------> Analog X
 
-	Sinclair Spectrum +2A/+3           Amiga 1200
-                                     
-    +-----------> Up                     +-----------> Button 3
-    | +---------> Fire                   | +---------> Right
-    | |                                  | | +-------> Left
-    | |   +-----> Ground                 | | | +-----> Down
-    | |   |                              | | | | +---> Up
-    | |   |                              | | | | |
-  _____________                        _____________
-5 \ o o x o x / 1                    5 \ o o o o o / 1
-   \ o o o o /                          \ o o o o /
-  9 `~~~~~~~' 6                        9 `~~~~~~~' 6
-     | | | |                              | | | |
-     | | | +----> Right                   | | | +----> Button 1
-     | | +------> Left                    | | +------> Power
-     | +--------> Ground                  | +--------> Ground
-     +----------> Down                    +----------> Button 2
+          Sinclair Spectrum +2A/+3           Amiga 1200
+
+      +-----------> Up                     +-----------> Button 3
+      | +---------> Fire                   | +---------> Right
+      | |                                  | | +-------> Left
+      | |   +-----> Ground                 | | | +-----> Down
+      | |   |                              | | | | +---> Up
+      | |   |                              | | | | |
+    _____________                        _____________
+  5 \ o o x o x / 1                    5 \ o o o o o / 1
+     \ o o o o /                          \ o o o o /
+    9 `~~~~~~~' 6                        9 `~~~~~~~' 6
+       | | | |                              | | | |
+       | | | +----> Right                   | | | +----> Button 1
+       | | +------> Left                    | | +------> Power
+       | +--------> Ground                  | +--------> Ground
+       +----------> Down                    +----------> Button 2
 
   And there were many others.
 
-2.2.1 Multisystem joysticks using db9.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  For the Multisystem joysticks, and their derivatives, the db9.c driver
+Multisystem joysticks using db9.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For the Multisystem joysticks, and their derivatives, the db9.c driver
 was written. It allows only one joystick / gamepad per parallel port, but
 the interface is easy to build and works with almost anything.
 
-  For the basic 1-button Multisystem joystick you connect its wires to the
-parallel port like this:
+For the basic 1-button Multisystem joystick you connect its wires to the
+parallel port like this::
 
-(pin  1) -----> Power
-(pin 18) -----> Ground
+    (pin  1) -----> Power
+    (pin 18) -----> Ground
 
-(pin  2) -----> Up
-(pin  3) -----> Down
-(pin  4) -----> Left
-(pin  5) -----> Right
-(pin  6) -----> Button 1
+    (pin  2) -----> Up
+    (pin  3) -----> Down
+    (pin  4) -----> Left
+    (pin  5) -----> Right
+    (pin  6) -----> Button 1
 
-  However, if the joystick is switch based (eg. clicks when you move it),
+However, if the joystick is switch based (eg. clicks when you move it),
 you might or might not, depending on your parallel port, need 10 kOhm pullup
-resistors on each of the direction and button signals, like this:
+resistors on each of the direction and button signals, like this::
 
-(pin 2) ------------+------> Up
-	  Resistor  |
-(pin 1) --[10kOhm]--+
+    (pin 2) ------------+------> Up
+              Resistor  |
+    (pin 1) --[10kOhm]--+
 
-  Try without, and if it doesn't work, add them. For TTL based joysticks /
+Try without, and if it doesn't work, add them. For TTL based joysticks /
 gamepads the pullups are not needed.
 
-  For joysticks with two buttons you connect the second button to pin 7 on
-the parallel port.
+For joysticks with two buttons you connect the second button to pin 7 on
+the parallel port::
 
-(pin 7) -----> Button 2
+    (pin 7) -----> Button 2
 
-  And that's it.
+And that's it.
 
-  On a side note, if you have already built a different adapter for use with
+On a side note, if you have already built a different adapter for use with
 the digital joystick driver 0.8.0.2, this is also supported by the db9.c
 driver, as device type 8. (See section 3.2)
 
-2.2.2 Multisystem joysticks using gamecon.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  For some people just one joystick per parallel port is not enough, and/or
+Multisystem joysticks using gamecon.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For some people just one joystick per parallel port is not enough, and/or
 want to use them on one parallel port together with NES/SNES/PSX pads. This is
 possible using the gamecon.c. It supports up to 5 devices of the above types,
 including 1 and 2 buttons Multisystem joysticks.
 
-  However, there is nothing for free. To allow more sticks to be used at
+However, there is nothing for free. To allow more sticks to be used at
 once, you need the sticks to be purely switch based (that is non-TTL), and
 not to need power. Just a plain simple six switches inside. If your
 joystick can do more (eg. turbofire) you'll need to disable it totally first
 if you want to use gamecon.c.
 
-  Also, the connection is a bit more complex. You'll need a bunch of diodes,
+Also, the connection is a bit more complex. You'll need a bunch of diodes,
 and one pullup resistor. First, you connect the Directions and the button
-the same as for db9, however with the diodes between.
+the same as for db9, however with the diodes between::
 
-	    Diodes
-(pin 2) -----|<|----> Up
-(pin 3) -----|<|----> Down
-(pin 4) -----|<|----> Left
-(pin 5) -----|<|----> Right
-(pin 6) -----|<|----> Button 1
+                Diodes
+    (pin 2) -----|<|----> Up
+    (pin 3) -----|<|----> Down
+    (pin 4) -----|<|----> Left
+    (pin 5) -----|<|----> Right
+    (pin 6) -----|<|----> Button 1
 
-  For two button sticks you also connect the other button.
+For two button sticks you also connect the other button::
 
-(pin 7) -----|<|----> Button 2
+    (pin 7) -----|<|----> Button 2
 
-  And finally, you connect the Ground wire of the joystick, like done in
+And finally, you connect the Ground wire of the joystick, like done in
 this little schematic to Power and Data on the parallel port, as described
 for the NES / SNES pads in section 2.1 of this file - that is, one data pin
-for each joystick. The power source is shared.
+for each joystick. The power source is shared::
 
-Data    ------------+-----> Ground
-	  Resistor  |
-Power   --[10kOhm]--+
+    Data    ------------+-----> Ground
+              Resistor  |
+    Power   --[10kOhm]--+
 
-  And that's all, here we go!
+And that's all, here we go!
 
-2.2.3 Multisystem joysticks using turbografx.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The TurboGraFX interface, designed by
+Multisystem joysticks using turbografx.c
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The TurboGraFX interface, designed by
 
 	Steffen Schwenke <schwenke@burg-halle.de>
 
-  allows up to 7 Multisystem joysticks connected to the parallel port. In
+allows up to 7 Multisystem joysticks connected to the parallel port. In
 Steffen's version, there is support for up to 5 buttons per joystick.  However,
 since this doesn't work reliably on all parallel ports, the turbografx.c driver
 supports only one button per joystick. For more information on how to build the
-interface, see
+interface, see:
 
 	http://www2.burg-halle.de/~schwenke/parport.html
 
-2.3 Sony Playstation
-~~~~~~~~~~~~~~~~~~~~
+Sony Playstation
+----------------
 
-  The PSX controller is supported by the gamecon.c. Pinout of the PSX
-controller (compatible with DirectPadPro):
+The PSX controller is supported by the gamecon.c. Pinout of the PSX
+controller (compatible with DirectPadPro)::
 
-  +---------+---------+---------+
-9 | o  o  o | o  o  o | o  o  o | 1               parallel
-   \________|_________|________/                  port pins
-    |  |      |  |  |   |
-    |  |      |  |  |   +-------->  Clock    ---  (4)
-    |  |      |  |  +------------>  Select   ---  (3)
-    |  |      |  +--------------->  Power    ---  (5-9)
-    |  |      +------------------>  Ground   ---  (18-25)
-    |  +------------------------->  Command  ---  (2)
-    +---------------------------->  Data     ---  (one of 10,11,12,13,15)
+    +---------+---------+---------+
+  9 | o  o  o | o  o  o | o  o  o | 1               parallel
+     \________|_________|________/                  port pins
+      |  |      |  |  |   |
+      |  |      |  |  |   +-------->  Clock    ---  (4)
+      |  |      |  |  +------------>  Select   ---  (3)
+      |  |      |  +--------------->  Power    ---  (5-9)
+      |  |      +------------------>  Ground   ---  (18-25)
+      |  +------------------------->  Command  ---  (2)
+      +---------------------------->  Data     ---  (one of 10,11,12,13,15)
 
-  The driver supports these controllers:
+The driver supports these controllers:
 
  * Standard PSX Pad
  * NegCon PSX Pad
@@ -336,207 +352,223 @@ controller (compatible with DirectPadPro):
  * PSX Rumble Pad
  * PSX DDR Pad
 
-2.4 Sega
-~~~~~~~~
-  All the Sega controllers are more or less based on the standard 2-button
+Sega
+----
+
+All the Sega controllers are more or less based on the standard 2-button
 Multisystem joystick. However, since they don't use switches and use TTL
 logic, the only driver usable with them is the db9.c driver.
 
-2.4.1 Sega Master System
-~~~~~~~~~~~~~~~~~~~~~~~~
-  The SMS gamepads are almost exactly the same as normal 2-button
+Sega Master System
+~~~~~~~~~~~~~~~~~~
+
+The SMS gamepads are almost exactly the same as normal 2-button
 Multisystem joysticks. Set the driver to Multi2 mode, use the corresponding
-parallel port pins, and the following schematic:
+parallel port pins, and the following schematic::
 
-    +-----------> Power
-    | +---------> Right
-    | | +-------> Left
-    | | | +-----> Down
-    | | | | +---> Up
-    | | | | |
-  _____________
-5 \ o o o o o / 1
-   \ o o x o /
-  9 `~~~~~~~' 6
-     | |   |
-     | |   +----> Button 1
-     | +--------> Ground
-     +----------> Button 2
+      +-----------> Power
+      | +---------> Right
+      | | +-------> Left
+      | | | +-----> Down
+      | | | | +---> Up
+      | | | | |
+    _____________
+  5 \ o o o o o / 1
+     \ o o x o /
+    9 `~~~~~~~' 6
+       | |   |
+       | |   +----> Button 1
+       | +--------> Ground
+       +----------> Button 2
 
-2.4.2 Sega Genesis aka MegaDrive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  The Sega Genesis (in Europe sold as Sega MegaDrive) pads are an extension
+Sega Genesis aka MegaDrive
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Sega Genesis (in Europe sold as Sega MegaDrive) pads are an extension
 to the Sega Master System pads. They use more buttons (3+1, 5+1, 6+1).  Use
-the following schematic:
+the following schematic::
 
-    +-----------> Power
-    | +---------> Right
-    | | +-------> Left
-    | | | +-----> Down
-    | | | | +---> Up
-    | | | | |
-  _____________
-5 \ o o o o o / 1
-   \ o o o o /
-  9 `~~~~~~~' 6
-     | | | |
-     | | | +----> Button 1
-     | | +------> Select
-     | +--------> Ground
-     +----------> Button 2
+        +-----------> Power
+        | +---------> Right
+        | | +-------> Left
+        | | | +-----> Down
+        | | | | +---> Up
+        | | | | |
+      _____________
+    5 \ o o o o o / 1
+       \ o o o o /
+      9 `~~~~~~~' 6
+        | | | |
+        | | | +----> Button 1
+        | | +------> Select
+        | +--------> Ground
+        +----------> Button 2
 
-  The Select pin goes to pin 14 on the parallel port.
+The Select pin goes to pin 14 on the parallel port::
 
-(pin 14) -----> Select
+    (pin 14) -----> Select
 
-  The rest is the same as for Multi2 joysticks using db9.c
+The rest is the same as for Multi2 joysticks using db9.c
 
-2.4.3 Sega Saturn
-~~~~~~~~~~~~~~~~~
-  Sega Saturn has eight buttons, and to transfer that, without hacks like
+Sega Saturn
+~~~~~~~~~~~
+
+Sega Saturn has eight buttons, and to transfer that, without hacks like
 Genesis 6 pads use, it needs one more select pin. Anyway, it is still
 handled by the db9.c driver. Its pinout is very different from anything
-else.  Use this schematic:
+else.  Use this schematic::
 
-    +-----------> Select 1
-    | +---------> Power
-    | | +-------> Up
-    | | | +-----> Down
-    | | | | +---> Ground
-    | | | | |
-  _____________
-5 \ o o o o o / 1
-   \ o o o o /
-  9 `~~~~~~~' 6
-     | | | |
-     | | | +----> Select 2
-     | | +------> Right
-     | +--------> Left
-     +----------> Power
+      +-----------> Select 1
+      | +---------> Power
+      | | +-------> Up
+      | | | +-----> Down
+      | | | | +---> Ground
+      | | | | |
+    _____________
+  5 \ o o o o o / 1
+     \ o o o o /
+    9 `~~~~~~~' 6
+       | | | |
+       | | | +----> Select 2
+       | | +------> Right
+       | +--------> Left
+       +----------> Power
 
-  Select 1 is pin 14 on the parallel port, Select 2 is pin 16 on the
-parallel port.
+Select 1 is pin 14 on the parallel port, Select 2 is pin 16 on the
+parallel port::
 
-(pin 14) -----> Select 1
-(pin 16) -----> Select 2
+    (pin 14) -----> Select 1
+    (pin 16) -----> Select 2
 
-  The other pins (Up, Down, Right, Left, Power, Ground) are the same as for
+The other pins (Up, Down, Right, Left, Power, Ground) are the same as for
 Multi joysticks using db9.c
 
-3. The drivers
-~~~~~~~~~~~~~~
-  There are three drivers for the parallel port interfaces. Each, as
+The drivers
+===========
+
+There are three drivers for the parallel port interfaces. Each, as
 described above, allows to connect a different group of joysticks and pads.
 Here are described their command lines:
 
-3.1 gamecon.c
-~~~~~~~~~~~~~
-  Using gamecon.c you can connect up to five devices to one parallel port. It
-uses the following kernel/module command line:
+gamecon.c
+---------
+
+Using gamecon.c you can connect up to five devices to one parallel port. It
+uses the following kernel/module command line::
 
 	gamecon.map=port,pad1,pad2,pad3,pad4,pad5
 
-  Where 'port' the number of the parport interface (eg. 0 for parport0).
+Where ``port`` the number of the parport interface (eg. 0 for parport0).
 
-  And 'pad1' to 'pad5' are pad types connected to different data input pins
+And ``pad1`` to ``pad5`` are pad types connected to different data input pins
 (10,11,12,13,15), as described in section 2.1 of this file.
 
-  The types are:
+The types are:
 
-	Type | Joystick/Pad
-	--------------------
-	  0  | None
-	  1  | SNES pad
-	  2  | NES pad
-	  4  | Multisystem 1-button joystick
-	  5  | Multisystem 2-button joystick
-	  6  | N64 pad
-	  7  | Sony PSX controller
-	  8  | Sony PSX DDR controller
-	  9  | SNES mouse
+	===== =============================
+	Type  Joystick/Pad
+	===== =============================
+	  0   None
+	  1   SNES pad
+	  2   NES pad
+	  4   Multisystem 1-button joystick
+	  5   Multisystem 2-button joystick
+	  6   N64 pad
+	  7   Sony PSX controller
+	  8   Sony PSX DDR controller
+	  9   SNES mouse
+	===== =============================
 
-  The exact type of the PSX controller type is autoprobed when used, so
+The exact type of the PSX controller type is autoprobed when used, so
 hot swapping should work (but is not recommended).
 
-  Should you want to use more than one of parallel ports at once, you can use
+Should you want to use more than one of parallel ports at once, you can use
 gamecon.map2 and gamecon.map3 as additional command line parameters for two
 more parallel ports.
 
-  There are two options specific to PSX driver portion.  gamecon.psx_delay sets
+There are two options specific to PSX driver portion.  gamecon.psx_delay sets
 the command delay when talking to the controllers. The default of 25 should
 work but you can try lowering it for better performance. If your pads don't
 respond try raising it until they work. Setting the type to 8 allows the
 driver to be used with Dance Dance Revolution or similar games. Arrow keys are
 registered as key presses instead of X and Y axes.
 
-3.2 db9.c
-~~~~~~~~~
-  Apart from making an interface, there is nothing difficult on using the
-db9.c driver. It uses the following kernel/module command line:
+db9.c
+-----
+
+Apart from making an interface, there is nothing difficult on using the
+db9.c driver. It uses the following kernel/module command line::
 
 	db9.dev=port,type
 
-  Where 'port' is the number of the parport interface (eg. 0 for parport0).
+Where ``port`` is the number of the parport interface (eg. 0 for parport0).
 
-  Caveat here: This driver only works on bidirectional parallel ports. If
+Caveat here: This driver only works on bidirectional parallel ports. If
 your parallel port is recent enough, you should have no trouble with this.
 Old parallel ports may not have this feature.
 
-  'Type' is the type of joystick or pad attached:
+``Type`` is the type of joystick or pad attached:
 
-	Type | Joystick/Pad
-	--------------------
-	  0  | None
-	  1  | Multisystem 1-button joystick
-	  2  | Multisystem 2-button joystick
-	  3  | Genesis pad (3+1 buttons)
-	  5  | Genesis pad (5+1 buttons)
-	  6  | Genesis pad (6+2 buttons)
-	  7  | Saturn pad (8 buttons)
-	  8  | Multisystem 1-button joystick (v0.8.0.2 pin-out)
-	  9  | Two Multisystem 1-button joysticks (v0.8.0.2 pin-out) 
-	 10  | Amiga CD32 pad
+	===== ======================================================
+	Type  Joystick/Pad
+	===== ======================================================
+	  0   None
+	  1   Multisystem 1-button joystick
+	  2   Multisystem 2-button joystick
+	  3   Genesis pad (3+1 buttons)
+	  5   Genesis pad (5+1 buttons)
+	  6   Genesis pad (6+2 buttons)
+	  7   Saturn pad (8 buttons)
+	  8   Multisystem 1-button joystick (v0.8.0.2 pin-out)
+	  9   Two Multisystem 1-button joysticks (v0.8.0.2 pin-out)
+	 10   Amiga CD32 pad
+	===== ======================================================
 
-  Should you want to use more than one of these joysticks/pads at once, you
+Should you want to use more than one of these joysticks/pads at once, you
 can use db9.dev2 and db9.dev3 as additional command line parameters for two
 more joysticks/pads.
 
-3.3 turbografx.c
-~~~~~~~~~~~~~~~~
-  The turbografx.c driver uses a very simple kernel/module command line:
+turbografx.c
+------------
+
+The turbografx.c driver uses a very simple kernel/module command line::
 
 	turbografx.map=port,js1,js2,js3,js4,js5,js6,js7
 
-  Where 'port' is the number of the parport interface (eg. 0 for parport0).
+Where ``port`` is the number of the parport interface (eg. 0 for parport0).
 
-  'jsX' is the number of buttons the Multisystem joysticks connected to the
+``jsX`` is the number of buttons the Multisystem joysticks connected to the
 interface ports 1-7 have. For a standard multisystem joystick, this is 1.
 
-  Should you want to use more than one of these interfaces at once, you can
+Should you want to use more than one of these interfaces at once, you can
 use turbografx.map2 and turbografx.map3 as additional command line parameters
 for two more interfaces.
 
-3.4 PC parallel port pinout
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+PC parallel port pinout
+-----------------------
+
+::
+
 		  .----------------------------------------.
    At the PC:     \ 13 12 11 10  9  8  7  6  5  4  3  2  1 /
                    \  25 24 23 22 21 20 19 18 17 16 15 14 /
                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-	  Pin | Name    | Description
-	~~~~~~|~~~~~~~~~|~~~~~~~~~~
-	    1 | /STROBE | Strobe
-	  2-9 | D0-D7   | Data Bit 0-7
-	   10 | /ACK    | Acknowledge
-	   11 | BUSY    | Busy
-	   12 | PE      | Paper End
-	   13 | SELIN   | Select In
-	   14 | /AUTOFD | Autofeed
-	   15 | /ERROR  | Error
-	   16 | /INIT   | Initialize
-	   17 | /SEL    | Select
-	18-25 | GND     | Signal Ground
+======  =======  =============
+   Pin  Name     Description
+======  =======  =============
+     1  /STROBE  Strobe
+   2-9  D0-D7    Data Bit 0-7
+    10  /ACK     Acknowledge
+    11  BUSY     Busy
+    12  PE       Paper End
+    13  SELIN    Select In
+    14  /AUTOFD  Autofeed
+    15  /ERROR   Error
+    16  /INIT    Initialize
+    17  /SEL     Select
+ 18-25  GND      Signal Ground
+======  =======  =============
 
-3.5 End
-~~~~~~~
-  That's all, folks! Have fun!
+
+That's all, folks! Have fun!
-- 
2.9.3

[PATCH v2 21/37] docs: input/multi-touch-protocol: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/multi-touch-protocol.txt | 196 +++++++++++++--------------
 1 file changed, 94 insertions(+), 102 deletions(-)

diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt
index c51f1146f3bd..81775d7c1997 100644
--- a/Documentation/input/multi-touch-protocol.txt
+++ b/Documentation/input/multi-touch-protocol.txt
@@ -1,6 +1,10 @@
+.. include:: <isonum.txt>
+
+=========================
 Multi-touch (MT) Protocol
--------------------------
-	Copyright (C) 2009-2010	Henrik Rydberg <rydberg@euromail.se>
+=========================
+
+:Copyright: |copy| 2009-2010	Henrik Rydberg <rydberg@euromail.se>
 
 
 Introduction
@@ -47,12 +51,12 @@ The main difference between the stateless type A protocol and the stateful
 type B slot protocol lies in the usage of identifiable contacts to reduce
 the amount of data sent to userspace. The slot protocol requires the use of
 the ABS_MT_TRACKING_ID, either provided by the hardware or computed from
-the raw data [5].
+the raw data [#f5]_.
 
 For type A devices, the kernel driver should generate an arbitrary
 enumeration of the full set of anonymous contacts currently on the
 surface. The order in which the packets appear in the event stream is not
-important.  Event filtering and finger tracking is left to user space [3].
+important.  Event filtering and finger tracking is left to user space [#f3]_.
 
 For type B devices, the kernel driver should associate a slot with each
 identified contact, and use that slot to propagate changes for the contact.
@@ -86,7 +90,7 @@ Protocol Example A
 ------------------
 
 Here is what a minimal event sequence for a two-contact touch would look
-like for a type A device:
+like for a type A device::
 
    ABS_MT_POSITION_X x[0]
    ABS_MT_POSITION_Y y[0]
@@ -100,14 +104,14 @@ The sequence after moving one of the contacts looks exactly the same; the
 raw data for all present contacts are sent between every synchronization
 with SYN_REPORT.
 
-Here is the sequence after lifting the first contact:
+Here is the sequence after lifting the first contact::
 
    ABS_MT_POSITION_X x[1]
    ABS_MT_POSITION_Y y[1]
    SYN_MT_REPORT
    SYN_REPORT
 
-And here is the sequence after lifting the second contact:
+And here is the sequence after lifting the second contact::
 
    SYN_MT_REPORT
    SYN_REPORT
@@ -122,7 +126,7 @@ Protocol Example B
 ------------------
 
 Here is what a minimal event sequence for a two-contact touch would look
-like for a type B device:
+like for a type B device::
 
    ABS_MT_SLOT 0
    ABS_MT_TRACKING_ID 45
@@ -134,13 +138,13 @@ like for a type B device:
    ABS_MT_POSITION_Y y[1]
    SYN_REPORT
 
-Here is the sequence after moving contact 45 in the x direction:
+Here is the sequence after moving contact 45 in the x direction::
 
    ABS_MT_SLOT 0
    ABS_MT_POSITION_X x[0]
    SYN_REPORT
 
-Here is the sequence after lifting the contact in slot 0:
+Here is the sequence after lifting the contact in slot 0::
 
    ABS_MT_TRACKING_ID -1
    SYN_REPORT
@@ -149,7 +153,7 @@ The slot being modified is already 0, so the ABS_MT_SLOT is omitted.  The
 message removes the association of slot 0 with contact 45, thereby
 destroying contact 45 and freeing slot 0 to be reused for another contact.
 
-Finally, here is the sequence after lifting the second contact:
+Finally, here is the sequence after lifting the second contact::
 
    ABS_MT_SLOT 1
    ABS_MT_TRACKING_ID -1
@@ -181,6 +185,8 @@ ABS_MT_PRESSURE may be used to provide the pressure on the contact area
 instead. Devices capable of contact hovering can use ABS_MT_DISTANCE to
 indicate the distance between the contact and the surface.
 
+::
+
 
 	  Linux MT                               Win8
          __________                     _______________________
@@ -212,7 +218,7 @@ via ABS_MT_BLOB_ID.
 
 The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
 finger or a pen or something else. Finally, the ABS_MT_TRACKING_ID event
-may be used to track identified contacts over time [5].
+may be used to track identified contacts over time [#f5]_.
 
 In the type B protocol, ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID are
 implicitly handled by input core; drivers should instead call
@@ -223,117 +229,103 @@ Event Semantics
 ---------------
 
 ABS_MT_TOUCH_MAJOR
-
-The length of the major axis of the contact. The length should be given in
-surface units. If the surface has an X times Y resolution, the largest
-possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4].
+    The length of the major axis of the contact. The length should be given in
+    surface units. If the surface has an X times Y resolution, the largest
+    possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [#f4]_.
 
 ABS_MT_TOUCH_MINOR
-
-The length, in surface units, of the minor axis of the contact. If the
-contact is circular, this event can be omitted [4].
+    The length, in surface units, of the minor axis of the contact. If the
+    contact is circular, this event can be omitted [#f4]_.
 
 ABS_MT_WIDTH_MAJOR
-
-The length, in surface units, of the major axis of the approaching
-tool. This should be understood as the size of the tool itself. The
-orientation of the contact and the approaching tool are assumed to be the
-same [4].
+    The length, in surface units, of the major axis of the approaching
+    tool. This should be understood as the size of the tool itself. The
+    orientation of the contact and the approaching tool are assumed to be the
+    same [#f4]_.
 
 ABS_MT_WIDTH_MINOR
+    The length, in surface units, of the minor axis of the approaching
+    tool. Omit if circular [#f4]_.
 
-The length, in surface units, of the minor axis of the approaching
-tool. Omit if circular [4].
-
-The above four values can be used to derive additional information about
-the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates
-the notion of pressure. The fingers of the hand and the palm all have
-different characteristic widths.
+    The above four values can be used to derive additional information about
+    the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates
+    the notion of pressure. The fingers of the hand and the palm all have
+    different characteristic widths.
 
 ABS_MT_PRESSURE
-
-The pressure, in arbitrary units, on the contact area. May be used instead
-of TOUCH and WIDTH for pressure-based devices or any device with a spatial
-signal intensity distribution.
+    The pressure, in arbitrary units, on the contact area. May be used instead
+    of TOUCH and WIDTH for pressure-based devices or any device with a spatial
+    signal intensity distribution.
 
 ABS_MT_DISTANCE
-
-The distance, in surface units, between the contact and the surface. Zero
-distance means the contact is touching the surface. A positive number means
-the contact is hovering above the surface.
+    The distance, in surface units, between the contact and the surface. Zero
+    distance means the contact is touching the surface. A positive number means
+    the contact is hovering above the surface.
 
 ABS_MT_ORIENTATION
+    The orientation of the touching ellipse. The value should describe a signed
+    quarter of a revolution clockwise around the touch center. The signed value
+    range is arbitrary, but zero should be returned for an ellipse aligned with
+    the Y axis of the surface, a negative value when the ellipse is turned to
+    the left, and a positive value when the ellipse is turned to the
+    right. When completely aligned with the X axis, the range max should be
+    returned.
 
-The orientation of the touching ellipse. The value should describe a signed
-quarter of a revolution clockwise around the touch center. The signed value
-range is arbitrary, but zero should be returned for an ellipse aligned with
-the Y axis of the surface, a negative value when the ellipse is turned to
-the left, and a positive value when the ellipse is turned to the
-right. When completely aligned with the X axis, the range max should be
-returned.
+    Touch ellipsis are symmetrical by default. For devices capable of true 360
+    degree orientation, the reported orientation must exceed the range max to
+    indicate more than a quarter of a revolution. For an upside-down finger,
+    range max * 2 should be returned.
 
-Touch ellipsis are symmetrical by default. For devices capable of true 360
-degree orientation, the reported orientation must exceed the range max to
-indicate more than a quarter of a revolution. For an upside-down finger,
-range max * 2 should be returned.
-
-Orientation can be omitted if the touch area is circular, or if the
-information is not available in the kernel driver. Partial orientation
-support is possible if the device can distinguish between the two axis, but
-not (uniquely) any values in between. In such cases, the range of
-ABS_MT_ORIENTATION should be [0, 1] [4].
+    Orientation can be omitted if the touch area is circular, or if the
+    information is not available in the kernel driver. Partial orientation
+    support is possible if the device can distinguish between the two axis, but
+    not (uniquely) any values in between. In such cases, the range of
+    ABS_MT_ORIENTATION should be [0, 1] [#f4]_.
 
 ABS_MT_POSITION_X
-
-The surface X coordinate of the center of the touching ellipse.
+    The surface X coordinate of the center of the touching ellipse.
 
 ABS_MT_POSITION_Y
-
-The surface Y coordinate of the center of the touching ellipse.
+    The surface Y coordinate of the center of the touching ellipse.
 
 ABS_MT_TOOL_X
-
-The surface X coordinate of the center of the approaching tool. Omit if
-the device cannot distinguish between the intended touch point and the
-tool itself.
+    The surface X coordinate of the center of the approaching tool. Omit if
+    the device cannot distinguish between the intended touch point and the
+    tool itself.
 
 ABS_MT_TOOL_Y
+    The surface Y coordinate of the center of the approaching tool. Omit if the
+    device cannot distinguish between the intended touch point and the tool
+    itself.
 
-The surface Y coordinate of the center of the approaching tool. Omit if the
-device cannot distinguish between the intended touch point and the tool
-itself.
-
-The four position values can be used to separate the position of the touch
-from the position of the tool. If both positions are present, the major
-tool axis points towards the touch point [1]. Otherwise, the tool axes are
-aligned with the touch axes.
+    The four position values can be used to separate the position of the touch
+    from the position of the tool. If both positions are present, the major
+    tool axis points towards the touch point [#f1]_. Otherwise, the tool axes are
+    aligned with the touch axes.
 
 ABS_MT_TOOL_TYPE
-
-The type of approaching tool. A lot of kernel drivers cannot distinguish
-between different tool types, such as a finger or a pen. In such cases, the
-event should be omitted. The protocol currently supports MT_TOOL_FINGER,
-MT_TOOL_PEN, and MT_TOOL_PALM [2]. For type B devices, this event is handled
-by input core; drivers should instead use input_mt_report_slot_state().
-A contact's ABS_MT_TOOL_TYPE may change over time while still touching the
-device, because the firmware may not be able to determine which tool is being
-used when it first appears.
+    The type of approaching tool. A lot of kernel drivers cannot distinguish
+    between different tool types, such as a finger or a pen. In such cases, the
+    event should be omitted. The protocol currently supports MT_TOOL_FINGER,
+    MT_TOOL_PEN, and MT_TOOL_PALM [#f2]_. For type B devices, this event is
+    handled by input core; drivers should instead use
+    input_mt_report_slot_state(). A contact's ABS_MT_TOOL_TYPE may change over
+    time while still touching the device, because the firmware may not be able
+    to determine which tool is being used when it first appears.
 
 ABS_MT_BLOB_ID
-
-The BLOB_ID groups several packets together into one arbitrarily shaped
-contact. The sequence of points forms a polygon which defines the shape of
-the contact. This is a low-level anonymous grouping for type A devices, and
-should not be confused with the high-level trackingID [5]. Most type A
-devices do not have blob capability, so drivers can safely omit this event.
+    The BLOB_ID groups several packets together into one arbitrarily shaped
+    contact. The sequence of points forms a polygon which defines the shape of
+    the contact. This is a low-level anonymous grouping for type A devices, and
+    should not be confused with the high-level trackingID [#f5]_. Most type A
+    devices do not have blob capability, so drivers can safely omit this event.
 
 ABS_MT_TRACKING_ID
-
-The TRACKING_ID identifies an initiated contact throughout its life cycle
-[5]. The value range of the TRACKING_ID should be large enough to ensure
-unique identification of a contact maintained over an extended period of
-time. For type B devices, this event is handled by input core; drivers
-should instead use input_mt_report_slot_state().
+    The TRACKING_ID identifies an initiated contact throughout its life cycle
+    [#f5]_. The value range of the TRACKING_ID should be large enough to ensure
+    unique identification of a contact maintained over an extended period of
+    time. For type B devices, this event is handled by input core; drivers
+    should instead use input_mt_report_slot_state().
 
 
 Event Computation
@@ -346,7 +338,7 @@ this section gives recipes for how to compute certain events.
 For devices reporting contacts as rectangular shapes, signed orientation
 cannot be obtained. Assuming X and Y are the lengths of the sides of the
 touching rectangle, here is a simple formula that retains the most
-information possible:
+information possible::
 
    ABS_MT_TOUCH_MAJOR := max(X, Y)
    ABS_MT_TOUCH_MINOR := min(X, Y)
@@ -356,7 +348,7 @@ The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that
 the device can distinguish between a finger along the Y axis (0) and a
 finger along the X axis (1).
 
-For win8 devices with both T and C coordinates, the position mapping is
+For win8 devices with both T and C coordinates, the position mapping is::
 
    ABS_MT_POSITION_X := T_X
    ABS_MT_POSITION_Y := T_Y
@@ -365,7 +357,7 @@ For win8 devices with both T and C coordinates, the position mapping is
 
 Unfortunately, there is not enough information to specify both the touching
 ellipse and the tool ellipse, so one has to resort to approximations.  One
-simple scheme, which is compatible with earlier usage, is:
+simple scheme, which is compatible with earlier usage, is::
 
    ABS_MT_TOUCH_MAJOR := min(X, Y)
    ABS_MT_TOUCH_MINOR := <not used>
@@ -386,7 +378,7 @@ The process of finger tracking, i.e., to assign a unique trackingID to each
 initiated contact on the surface, is a Euclidian Bipartite Matching
 problem.  At each event synchronization, the set of actual contacts is
 matched to the set of contacts from the previous synchronization. A full
-implementation can be found in [3].
+implementation can be found in [#f3]_.
 
 
 Gestures
@@ -411,8 +403,8 @@ 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.
 
-[1] Also, the difference (TOOL_X - POSITION_X) can be used to model tilt.
-[2] The list can of course be extended.
-[3] The mtdev project: http://bitmath.org/code/mtdev/.
-[4] See the section on event computation.
-[5] See the section on finger tracking.
+.. [#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/.
+.. [#f4] See the section on event computation.
+.. [#f5] See the section on finger tracking.
-- 
2.9.3

[PATCH v2 22/37] docs: input/notifier: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/notifier.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/input/notifier.txt b/Documentation/input/notifier.txt
index 95172ca6f3d2..161350cb865e 100644
--- a/Documentation/input/notifier.txt
+++ b/Documentation/input/notifier.txt
@@ -1,4 +1,6 @@
+=================
 Keyboard notifier
+=================
 
 One can use register_keyboard_notifier to get called back on keyboard
 events (see kbd_keycode() function for details).  The passed structure is
@@ -23,9 +25,9 @@ For each kind of event but the last, the callback may return NOTIFY_STOP in
 order to "eat" the event: the notify loop is stopped and the keyboard event is
 dropped.
 
-In a rough C snippet, we have:
+In a rough C snippet, we have::
 
-kbd_keycode(keycode) {
+    kbd_keycode(keycode) {
 	...
 	params.value = keycode;
 	if (notifier_call_chain(KBD_KEYCODE,&params) == NOTIFY_STOP)
@@ -47,6 +49,6 @@ kbd_keycode(keycode) {
 		return;
 	apply keysym;
 	notifier_call_chain(KBD_POST_KEYSYM,&params);
-}
+    }
 
-NOTE: This notifier is usually called from interrupt context.
+.. note:: This notifier is usually called from interrupt context.
-- 
2.9.3

[PATCH v2 23/37] docs: input/ntrig: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/ntrig.txt | 49 ++++++++++++++++++++++++++-----------------
 1 file changed, 30 insertions(+), 19 deletions(-)

diff --git a/Documentation/input/ntrig.txt b/Documentation/input/ntrig.txt
index be1fd981f73f..a6b22ce6c61c 100644
--- a/Documentation/input/ntrig.txt
+++ b/Documentation/input/ntrig.txt
@@ -1,7 +1,11 @@
+.. 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
-- 
2.9.3

[PATCH v2 24/37] docs: input/rotary-encoder: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/rotary-encoder.txt | 74 +++++++++++++++++-----------------
 1 file changed, 38 insertions(+), 36 deletions(-)

diff --git a/Documentation/input/rotary-encoder.txt b/Documentation/input/rotary-encoder.txt
index 46a74f0c551a..4695bea67f9b 100644
--- a/Documentation/input/rotary-encoder.txt
+++ b/Documentation/input/rotary-encoder.txt
@@ -1,8 +1,11 @@
+============================================================
 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,16 +68,16 @@ 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
@@ -93,34 +96,33 @@ 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 */
+    /* board support file example */
 
-#include <linux/input.h>
-#include <linux/rotary_encoder.h>
+    #include <linux/input.h>
+    #include <linux/rotary_encoder.h>
 
-#define GPIO_ROTARY_A 1
-#define GPIO_ROTARY_B 2
+    #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,
-	}
-};
+    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,
+	    }
+    };
-- 
2.9.3

[PATCH v2 25/37] docs: input/sentelic: convert it to ReST format

[Mauro Carvalho Chehab]

This file has its own particular format that doesn't match any
markup one.

Manually change it to get something that would be readable
using ReST markup language.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/sentelic.txt | 1000 ++++++++++++++++++++------------------
 1 file changed, 514 insertions(+), 486 deletions(-)

diff --git a/Documentation/input/sentelic.txt b/Documentation/input/sentelic.txt
index 89251e2a3eba..d1a476f973b1 100644
--- a/Documentation/input/sentelic.txt
+++ b/Documentation/input/sentelic.txt
@@ -1,411 +1,437 @@
-Copyright (C) 2002-2011 Sentelic Corporation.
-Last update: Dec-07-2011
+.. include:: <isonum.txt>
+
+===============
+Sentelic Driver
+===============
+
+
+:Copyright: |copy| 2002-2011 Sentelic Corporation.
+
+:Last update: Dec-07-2011
+
+Finger Sensing Pad Intellimouse Mode(scrolling wheel, 4th and 5th buttons)
+==========================================================================
 
-==============================================================================
-* Finger Sensing Pad Intellimouse Mode(scrolling wheel, 4th and 5th buttons)
-==============================================================================
 A) MSID 4: Scrolling wheel mode plus Forward page(4th button) and Backward
    page (5th button)
-@1. Set sample rate to 200;
-@2. Set sample rate to 200;
-@3. Set sample rate to 80;
-@4. Issuing the "Get device ID" command (0xF2) and waits for the response;
-@5. FSP will respond 0x04.
-
-Packet 1
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |Y|X|y|x|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 | | |B|F|W|W|W|W|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7 => Y overflow
-        Bit6 => X overflow
-        Bit5 => Y sign bit
-        Bit4 => X sign bit
-        Bit3 => 1
-        Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X Movement(9-bit 2's complement integers)
-Byte 3: Y Movement(9-bit 2's complement integers)
-Byte 4: Bit3~Bit0 => the scrolling wheel's movement since the last data report.
-                     valid values, -8 ~ +7
-        Bit4 => 1 = 4th mouse button is pressed, Forward one page.
-                0 = 4th mouse button is not pressed.
-        Bit5 => 1 = 5th mouse button is pressed, Backward one page.
-                0 = 5th mouse button is not pressed.
-
-B) MSID 6: Horizontal and Vertical scrolling.
-@ Set bit 1 in register 0x40 to 1
-
-# FSP replaces scrolling wheel's movement as 4 bits to show horizontal and
-  vertical scrolling.
-
-Packet 1
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |Y|X|y|x|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 | | |B|F|r|l|u|d|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7 => Y overflow
-        Bit6 => X overflow
-        Bit5 => Y sign bit
-        Bit4 => X sign bit
-        Bit3 => 1
-        Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X Movement(9-bit 2's complement integers)
-Byte 3: Y Movement(9-bit 2's complement integers)
-Byte 4: Bit0 => the Vertical scrolling movement downward.
-	Bit1 => the Vertical scrolling movement upward.
-	Bit2 => the Horizontal scrolling movement leftward.
-	Bit3 => the Horizontal scrolling movement rightward.
-        Bit4 => 1 = 4th mouse button is pressed, Forward one page.
-                0 = 4th mouse button is not pressed.
-        Bit5 => 1 = 5th mouse button is pressed, Backward one page.
-                0 = 5th mouse button is not pressed.
-
-C) MSID 7:
-# FSP uses 2 packets (8 Bytes) to represent Absolute Position.
-  so we have PACKET NUMBER to identify packets.
+
+1. Set sample rate to 200;
+2. Set sample rate to 200;
+3. Set sample rate to 80;
+4. Issuing the "Get device ID" command (0xF2) and waits for the response;
+5. FSP will respond 0x04.
+
+::
+
+    Packet 1
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |Y|X|y|x|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 | | |B|F|W|W|W|W|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7 => Y overflow
+	    Bit6 => X overflow
+	    Bit5 => Y sign bit
+	    Bit4 => X sign bit
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X Movement(9-bit 2's complement integers)
+    Byte 3: Y Movement(9-bit 2's complement integers)
+    Byte 4: Bit3~Bit0 => the scrolling wheel's movement since the last data report.
+			valid values, -8 ~ +7
+	    Bit4 => 1 = 4th mouse button is pressed, Forward one page.
+		    0 = 4th mouse button is not pressed.
+	    Bit5 => 1 = 5th mouse button is pressed, Backward one page.
+		    0 = 5th mouse button is not pressed.
+
+B) MSID 6: Horizontal and Vertical scrolling
+
+- Set bit 1 in register 0x40 to 1
+
+FSP replaces scrolling wheel's movement as 4 bits to show horizontal and
+vertical scrolling.
+
+::
+
+    Packet 1
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |Y|X|y|x|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 | | |B|F|r|l|u|d|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7 => Y overflow
+	    Bit6 => X overflow
+	    Bit5 => Y sign bit
+	    Bit4 => X sign bit
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X Movement(9-bit 2's complement integers)
+    Byte 3: Y Movement(9-bit 2's complement integers)
+    Byte 4: Bit0 => the Vertical scrolling movement downward.
+	    Bit1 => the Vertical scrolling movement upward.
+	    Bit2 => the Horizontal scrolling movement leftward.
+	    Bit3 => the Horizontal scrolling movement rightward.
+	    Bit4 => 1 = 4th mouse button is pressed, Forward one page.
+		    0 = 4th mouse button is not pressed.
+	    Bit5 => 1 = 5th mouse button is pressed, Backward one page.
+		    0 = 5th mouse button is not pressed.
+
+C) MSID 7
+
+FSP uses 2 packets (8 Bytes) to represent Absolute Position.
+so we have PACKET NUMBER to identify packets.
+
   If PACKET NUMBER is 0, the packet is Packet 1.
   If PACKET NUMBER is 1, the packet is Packet 2.
   Please count this number in program.
 
-# MSID6 special packet will be enable at the same time when enable MSID 7.
-
-==============================================================================
-* Absolute position for STL3886-G0.
-==============================================================================
-@ Set bit 2 or 3 in register 0x40 to 1
-@ Set bit 6 in register 0x40 to 1
-
-Packet 1 (ABSOLUTE POSITION)
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|V|1|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|d|u|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordination packet
-                  => 10, Notify packet
-        Bit5 => valid bit
-        Bit4 => 1
-        Bit3 => 1
-        Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-        Bit3~Bit2 => X coordinate (ypos[1:0])
-        Bit4 => scroll up
-        Bit5 => scroll down
-        Bit6 => scroll left
-        Bit7 => scroll right
-
-Notify Packet for G0
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |1|0|0|1|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |M|M|M|M|M|M|M|M|  4 |0|0|0|0|0|0|0|0|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordination packet
-                  => 10, Notify packet
-        Bit5 => 0
-        Bit4 => 1
-        Bit3 => 1
-        Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: Message Type => 0x5A (Enable/Disable status packet)
-        Mode Type => 0xA5 (Normal/Icon mode status)
-Byte 3: Message Type => 0x00 (Disabled)
-                     => 0x01 (Enabled)
-        Mode Type    => 0x00 (Normal)
-                     => 0x01 (Icon)
-Byte 4: Bit7~Bit0 => Don't Care
-
-==============================================================================
-* Absolute position for STL3888-Ax.
-==============================================================================
-Packet 1 (ABSOLUTE POSITION)
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|V|A|1|L|0|1|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |x|x|y|y|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordination packet
-                  => 10, Notify packet
-                  => 11, Normal data packet with on-pad click
-        Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
-                When both fingers are up, the last two reports have zero valid
-                bit.
-        Bit4 => arc
-        Bit3 => 1
-        Bit2 => Left Button, 1 is pressed, 0 is released.
-        Bit1 => 0
-        Bit0 => 1
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-        Bit3~Bit2 => X coordinate (ypos[1:0])
-        Bit5~Bit4 => y1_g
-        Bit7~Bit6 => x1_g
-
-Packet 2 (ABSOLUTE POSITION)
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|V|A|1|R|1|0|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |x|x|y|y|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordinates packet
-                  => 10, Notify packet
-                  => 11, Normal data packet with on-pad click
-        Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
-                When both fingers are up, the last two reports have zero valid
-                bit.
-        Bit4 => arc
-        Bit3 => 1
-        Bit2 => Right Button, 1 is pressed, 0 is released.
-        Bit1 => 1
-        Bit0 => 0
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-        Bit3~Bit2 => X coordinate (ypos[1:0])
-        Bit5~Bit4 => y2_g
-        Bit7~Bit6 => x2_g
-
-Notify Packet for STL3888-Ax
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |1|0|1|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|d|u|0|0|0|0|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordinates packet
-                  => 10, Notify packet
-                  => 11, Normal data packet with on-pad click
-        Bit5 => 1
-        Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1):
-                0: left button is generated by the on-pad command
-                1: left button is generated by the external button
-        Bit3 => 1
-        Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode)
-Byte 3: Bit7~Bit6 => Don't care
-        Bit5~Bit4 => Number of fingers
-        Bit3~Bit1 => Reserved
-        Bit0 => 1: enter gesture mode; 0: leaving gesture mode
-Byte 4: Bit7 => scroll right button
-        Bit6 => scroll left button
-        Bit5 => scroll down button
-        Bit4 => scroll up button
-            * Note that if gesture and additional button (Bit4~Bit7)
-              happen at the same time, the button information will not
-              be sent.
-        Bit3~Bit0 => Reserved
+MSID6 special packet will be enable at the same time when enable MSID 7.
+
+Absolute position for STL3886-G0
+================================
+
+1. Set bit 2 or 3 in register 0x40 to 1
+2. Set bit 6 in register 0x40 to 1
+
+::
+
+    Packet 1 (ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|1|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|d|u|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordination packet
+		    => 10, Notify packet
+	    Bit5 => valid bit
+	    Bit4 => 1
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit4 => scroll up
+	    Bit5 => scroll down
+	    Bit6 => scroll left
+	    Bit7 => scroll right
+
+    Notify Packet for G0
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |1|0|0|1|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |M|M|M|M|M|M|M|M|  4 |0|0|0|0|0|0|0|0|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordination packet
+		    => 10, Notify packet
+	    Bit5 => 0
+	    Bit4 => 1
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: Message Type => 0x5A (Enable/Disable status packet)
+	    Mode Type => 0xA5 (Normal/Icon mode status)
+    Byte 3: Message Type => 0x00 (Disabled)
+			=> 0x01 (Enabled)
+	    Mode Type    => 0x00 (Normal)
+			=> 0x01 (Icon)
+    Byte 4: Bit7~Bit0 => Don't Care
+
+Absolute position for STL3888-Ax
+================================
+
+::
+
+    Packet 1 (ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|A|1|L|0|1|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |x|x|y|y|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordination packet
+		    => 10, Notify packet
+		    => 11, Normal data packet with on-pad click
+	    Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
+		    When both fingers are up, the last two reports have zero valid
+		    bit.
+	    Bit4 => arc
+	    Bit3 => 1
+	    Bit2 => Left Button, 1 is pressed, 0 is released.
+	    Bit1 => 0
+	    Bit0 => 1
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit5~Bit4 => y1_g
+	    Bit7~Bit6 => x1_g
+
+    Packet 2 (ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|A|1|R|1|0|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |x|x|y|y|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordinates packet
+		    => 10, Notify packet
+		    => 11, Normal data packet with on-pad click
+	    Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
+		    When both fingers are up, the last two reports have zero valid
+		    bit.
+	    Bit4 => arc
+	    Bit3 => 1
+	    Bit2 => Right Button, 1 is pressed, 0 is released.
+	    Bit1 => 1
+	    Bit0 => 0
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit5~Bit4 => y2_g
+	    Bit7~Bit6 => x2_g
+
+    Notify Packet for STL3888-Ax
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |1|0|1|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|d|u|0|0|0|0|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordinates packet
+		    => 10, Notify packet
+		    => 11, Normal data packet with on-pad click
+	    Bit5 => 1
+	    Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1):
+		    0: left button is generated by the on-pad command
+		    1: left button is generated by the external button
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode)
+    Byte 3: Bit7~Bit6 => Don't care
+	    Bit5~Bit4 => Number of fingers
+	    Bit3~Bit1 => Reserved
+	    Bit0 => 1: enter gesture mode; 0: leaving gesture mode
+    Byte 4: Bit7 => scroll right button
+	    Bit6 => scroll left button
+	    Bit5 => scroll down button
+	    Bit4 => scroll up button
+		* Note that if gesture and additional button (Bit4~Bit7)
+		happen at the same time, the button information will not
+		be sent.
+	    Bit3~Bit0 => Reserved
 
 Sample sequence of Multi-finger, Multi-coordinate mode:
 
 	notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1,
 	abs pkt 2, ..., notify packet (valid bit == 0)
 
-==============================================================================
-* Absolute position for STL3888-B0.
-==============================================================================
-Packet 1(ABSOLUTE POSITION)
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|V|F|1|0|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|u|d|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordinates packet
-                  => 10, Notify packet
-                  => 11, Normal data packet with on-pad click
-        Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
-                When both fingers are up, the last two reports have zero valid
-                bit.
-        Bit4 => finger up/down information. 1: finger down, 0: finger up.
-        Bit3 => 1
-        Bit2 => finger index, 0 is the first finger, 1 is the second finger.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-        Bit3~Bit2 => X coordinate (ypos[1:0])
-        Bit4 => scroll down button
-        Bit5 => scroll up button
-        Bit6 => scroll left button
-        Bit7 => scroll right button
-
-Packet 2 (ABSOLUTE POSITION)
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|V|F|1|1|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|u|d|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordination packet
-                  => 10, Notify packet
-                  => 11, Normal data packet with on-pad click
-        Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
-                When both fingers are up, the last two reports have zero valid
-                bit.
-        Bit4 => finger up/down information. 1: finger down, 0: finger up.
-        Bit3 => 1
-        Bit2 => finger index, 0 is the first finger, 1 is the second finger.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-        Bit3~Bit2 => X coordinate (ypos[1:0])
-        Bit4 => scroll down button
-        Bit5 => scroll up button
-        Bit6 => scroll left button
-        Bit7 => scroll right button
-
-Notify Packet for STL3888-B0
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |1|0|1|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|u|d|0|0|0|0|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordination packet
-                  => 10, Notify packet
-                  => 11, Normal data packet with on-pad click
-        Bit5 => 1
-        Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1):
-                0: left button is generated by the on-pad command
-                1: left button is generated by the external button
-        Bit3 => 1
-        Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-        Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-        Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode)
-Byte 3: Bit7~Bit6 => Don't care
-        Bit5~Bit4 => Number of fingers
-        Bit3~Bit1 => Reserved
-        Bit0 => 1: enter gesture mode; 0: leaving gesture mode
-Byte 4: Bit7 => scroll right button
-        Bit6 => scroll left button
-        Bit5 => scroll up button
-        Bit4 => scroll down button
-            * Note that if gesture and additional button(Bit4~Bit7)
-              happen at the same time, the button information will not
-              be sent.
-        Bit3~Bit0 => Reserved
+Absolute position for STL3888-B0
+================================
+
+::
+
+    Packet 1(ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|F|1|0|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|u|d|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordinates packet
+		    => 10, Notify packet
+		    => 11, Normal data packet with on-pad click
+	    Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
+		    When both fingers are up, the last two reports have zero valid
+		    bit.
+	    Bit4 => finger up/down information. 1: finger down, 0: finger up.
+	    Bit3 => 1
+	    Bit2 => finger index, 0 is the first finger, 1 is the second finger.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit4 => scroll down button
+	    Bit5 => scroll up button
+	    Bit6 => scroll left button
+	    Bit7 => scroll right button
+
+    Packet 2 (ABSOLUTE POSITION)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|V|F|1|1|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|u|d|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordination packet
+		    => 10, Notify packet
+		    => 11, Normal data packet with on-pad click
+	    Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up.
+		    When both fingers are up, the last two reports have zero valid
+		    bit.
+	    Bit4 => finger up/down information. 1: finger down, 0: finger up.
+	    Bit3 => 1
+	    Bit2 => finger index, 0 is the first finger, 1 is the second finger.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit4 => scroll down button
+	    Bit5 => scroll up button
+	    Bit6 => scroll left button
+	    Bit7 => scroll right button
+
+Notify Packet for STL3888-B0::
+
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |1|0|1|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|u|d|0|0|0|0|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordination packet
+		    => 10, Notify packet
+		    => 11, Normal data packet with on-pad click
+	    Bit5 => 1
+	    Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1):
+		    0: left button is generated by the on-pad command
+		    1: left button is generated by the external button
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode)
+    Byte 3: Bit7~Bit6 => Don't care
+	    Bit5~Bit4 => Number of fingers
+	    Bit3~Bit1 => Reserved
+	    Bit0 => 1: enter gesture mode; 0: leaving gesture mode
+    Byte 4: Bit7 => scroll right button
+	    Bit6 => scroll left button
+	    Bit5 => scroll up button
+	    Bit4 => scroll down button
+		* Note that if gesture and additional button(Bit4~Bit7)
+		happen at the same time, the button information will not
+		be sent.
+	    Bit3~Bit0 => Reserved
 
 Sample sequence of Multi-finger, Multi-coordinate mode:
 
 	notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1,
 	abs pkt 2, ..., notify packet (valid bit == 0)
 
-==============================================================================
-* Absolute position for STL3888-Cx and STL3888-Dx.
-==============================================================================
-Single Finger, Absolute Coordinate Mode (SFAC)
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|0|P|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|B|F|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordinates packet
-                  => 10, Notify packet
-	Bit5 => Coordinate mode(always 0 in SFAC mode):
-		0: single-finger absolute coordinates (SFAC) mode
-		1: multi-finger, multiple coordinates (MFMC) mode
-	Bit4 => 0: The LEFT button is generated by on-pad command (OPC)
-		1: The LEFT button is generated by external button
-		Default is 1 even if the LEFT button is not pressed.
-	Bit3 => Always 1, as specified by PS/2 protocol.
-	Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-	Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-	Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-	Bit3~Bit2 => X coordinate (ypos[1:0])
-	Bit4 => 4th mouse button(forward one page)
-	Bit5 => 5th mouse button(backward one page)
-	Bit6 => scroll left button
-	Bit7 => scroll right button
-
-Multi Finger, Multiple Coordinates Mode (MFMC):
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |0|1|1|P|1|F|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|B|F|X|X|Y|Y|
-      |---------------|     |---------------|    |---------------|    |---------------|
-
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordination packet
-                  => 10, Notify packet
-	Bit5 => Coordinate mode (always 1 in MFMC mode):
-		0: single-finger absolute coordinates (SFAC) mode
-		1: multi-finger, multiple coordinates (MFMC) mode
-	Bit4 => 0: The LEFT button is generated by on-pad command (OPC)
-		1: The LEFT button is generated by external button
-		Default is 1 even if the LEFT button is not pressed.
-	Bit3 => Always 1, as specified by PS/2 protocol.
-	Bit2 => Finger index, 0 is the first finger, 1 is the second finger.
-		If bit 1 and 0 are all 1 and bit 4 is 0, the middle external
-		button is pressed.
-	Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-	Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: X coordinate (xpos[9:2])
-Byte 3: Y coordinate (ypos[9:2])
-Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
-	Bit3~Bit2 => X coordinate (ypos[1:0])
-	Bit4 => 4th mouse button(forward one page)
-	Bit5 => 5th mouse button(backward one page)
-	Bit6 => scroll left button
-	Bit7 => scroll right button
-
-  When one of the two fingers is up, the device will output four consecutive
+Absolute position for STL3888-Cx and STL3888-Dx
+===============================================
+
+::
+
+    Single Finger, Absolute Coordinate Mode (SFAC)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|0|P|1|M|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|B|F|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordinates packet
+		    => 10, Notify packet
+	    Bit5 => Coordinate mode(always 0 in SFAC mode):
+		    0: single-finger absolute coordinates (SFAC) mode
+		    1: multi-finger, multiple coordinates (MFMC) mode
+	    Bit4 => 0: The LEFT button is generated by on-pad command (OPC)
+		    1: The LEFT button is generated by external button
+		    Default is 1 even if the LEFT button is not pressed.
+	    Bit3 => Always 1, as specified by PS/2 protocol.
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit4 => 4th mouse button(forward one page)
+	    Bit5 => 5th mouse button(backward one page)
+	    Bit6 => scroll left button
+	    Bit7 => scroll right button
+
+    Multi Finger, Multiple Coordinates Mode (MFMC):
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |0|1|1|P|1|F|R|L|  2  |X|X|X|X|X|X|X|X|  3 |Y|Y|Y|Y|Y|Y|Y|Y|  4 |r|l|B|F|X|X|Y|Y|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordination packet
+		    => 10, Notify packet
+	    Bit5 => Coordinate mode (always 1 in MFMC mode):
+		    0: single-finger absolute coordinates (SFAC) mode
+		    1: multi-finger, multiple coordinates (MFMC) mode
+	    Bit4 => 0: The LEFT button is generated by on-pad command (OPC)
+		    1: The LEFT button is generated by external button
+		    Default is 1 even if the LEFT button is not pressed.
+	    Bit3 => Always 1, as specified by PS/2 protocol.
+	    Bit2 => Finger index, 0 is the first finger, 1 is the second finger.
+		    If bit 1 and 0 are all 1 and bit 4 is 0, the middle external
+		    button is pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: X coordinate (xpos[9:2])
+    Byte 3: Y coordinate (ypos[9:2])
+    Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0])
+	    Bit3~Bit2 => X coordinate (ypos[1:0])
+	    Bit4 => 4th mouse button(forward one page)
+	    Bit5 => 5th mouse button(backward one page)
+	    Bit6 => scroll left button
+	    Bit7 => scroll right button
+
+When one of the two fingers is up, the device will output four consecutive
 MFMC#0 report packets with zero X and Y to represent 1st finger is up or
 four consecutive MFMC#1 report packets with zero X and Y to represent that
 the 2nd finger is up.  On the other hand, if both fingers are up, the device
 will output four consecutive single-finger, absolute coordinate(SFAC) packets
 with zero X and Y.
 
-Notify Packet for STL3888-Cx/Dx
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |1|0|0|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|u|d|0|0|0|0|
-      |---------------|     |---------------|    |---------------|    |---------------|
+Notify Packet for STL3888-Cx/Dx::
 
-Byte 1: Bit7~Bit6 => 00, Normal data packet
-                  => 01, Absolute coordinates packet
-                  => 10, Notify packet
-	Bit5 => Always 0
-	Bit4 => 0: The LEFT button is generated by on-pad command(OPC)
-		1: The LEFT button is generated by external button
-		Default is 1 even if the LEFT button is not pressed.
-	Bit3 => 1
-	Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
-	Bit1 => Right Button, 1 is pressed, 0 is not pressed.
-	Bit0 => Left Button, 1 is pressed, 0 is not pressed.
-Byte 2: Message type:
-	0xba => gesture information
-	0xc0 => one finger hold-rotating gesture
-Byte 3: The first parameter for the received message:
-	0xba => gesture ID (refer to the 'Gesture ID' section)
-	0xc0 => region ID
-Byte 4: The second parameter for the received message:
-	0xba => N/A
-	0xc0 => finger up/down information
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |1|0|0|P|1|M|R|L|  2  |C|C|C|C|C|C|C|C|  3 |0|0|F|F|0|0|0|i|  4 |r|l|u|d|0|0|0|0|
+	  |---------------|     |---------------|    |---------------|    |---------------|
+
+    Byte 1: Bit7~Bit6 => 00, Normal data packet
+		    => 01, Absolute coordinates packet
+		    => 10, Notify packet
+	    Bit5 => Always 0
+	    Bit4 => 0: The LEFT button is generated by on-pad command(OPC)
+		    1: The LEFT button is generated by external button
+		    Default is 1 even if the LEFT button is not pressed.
+	    Bit3 => 1
+	    Bit2 => Middle Button, 1 is pressed, 0 is not pressed.
+	    Bit1 => Right Button, 1 is pressed, 0 is not pressed.
+	    Bit0 => Left Button, 1 is pressed, 0 is not pressed.
+    Byte 2: Message type:
+	    0xba => gesture information
+	    0xc0 => one finger hold-rotating gesture
+    Byte 3: The first parameter for the received message:
+	    0xba => gesture ID (refer to the 'Gesture ID' section)
+	    0xc0 => region ID
+    Byte 4: The second parameter for the received message:
+	    0xba => N/A
+	    0xc0 => finger up/down information
 
 Sample sequence of Multi-finger, Multi-coordinates mode:
 
@@ -416,50 +442,51 @@ Sample sequence of Multi-finger, Multi-coordinates mode:
 	That is, when the device is in MFMC mode, the host will receive
 	interleaved absolute coordinate packets for each finger.
 
-==============================================================================
-* FSP Enable/Disable packet
-==============================================================================
-   Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
-BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
-  1   |Y|X|0|0|1|M|R|L|  2  |0|1|0|1|1|0|1|E|  3 | | | | | | | | |  4 | | | | | | | | |
-      |---------------|     |---------------|    |---------------|    |---------------|
+FSP Enable/Disable packet
+=========================
 
-FSP will send out enable/disable packet when FSP receive PS/2 enable/disable
-command. Host will receive the packet which Middle, Right, Left button will
-be set. The packet only use byte 0 and byte 1 as a pattern of original packet.
-Ignore the other bytes of the packet.
+::
 
-Byte 1: Bit7 => 0, Y overflow
-        Bit6 => 0, X overflow
-	Bit5 => 0, Y sign bit
-        Bit4 => 0, X sign bit
-	Bit3 => 1
-	Bit2 => 1, Middle Button
-        Bit1 => 1, Right Button
-        Bit0 => 1, Left Button
-Byte 2: Bit7~1 => (0101101b)
-        Bit0 => 1 = Enable
-		0 = Disable
-Byte 3: Don't care
-Byte 4: Don't care (MOUSE ID 3, 4)
-Byte 5~8: Don't care (Absolute packet)
+    Bit 7 6 5 4 3 2 1 0       7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0      7 6 5 4 3 2 1 0
+    BYTE  |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------|
+      1   |Y|X|0|0|1|M|R|L|  2  |0|1|0|1|1|0|1|E|  3 | | | | | | | | |  4 | | | | | | | | |
+	  |---------------|     |---------------|    |---------------|    |---------------|
 
-==============================================================================
-* PS/2 Command Set
-==============================================================================
+    FSP will send out enable/disable packet when FSP receive PS/2 enable/disable
+    command. Host will receive the packet which Middle, Right, Left button will
+    be set. The packet only use byte 0 and byte 1 as a pattern of original packet.
+    Ignore the other bytes of the packet.
+
+    Byte 1: Bit7 => 0, Y overflow
+	    Bit6 => 0, X overflow
+	    Bit5 => 0, Y sign bit
+	    Bit4 => 0, X sign bit
+	    Bit3 => 1
+	    Bit2 => 1, Middle Button
+	    Bit1 => 1, Right Button
+	    Bit0 => 1, Left Button
+    Byte 2: Bit7~1 => (0101101b)
+	    Bit0 => 1 = Enable
+		    0 = Disable
+    Byte 3: Don't care
+    Byte 4: Don't care (MOUSE ID 3, 4)
+    Byte 5~8: Don't care (Absolute packet)
+
+PS/2 Command Set
+================
 
 FSP supports basic PS/2 commanding set and modes, refer to following URL for
 details about PS/2 commands:
 
 http://www.computer-engineering.org/ps2mouse/
 
-==============================================================================
-* Programming Sequence for Determining Packet Parsing Flow
-==============================================================================
+Programming Sequence for Determining Packet Parsing Flow
+========================================================
+
 1. Identify FSP by reading device ID(0x00) and version(0x01) register
 
-2a. For FSP version < STL3888 Cx, determine number of buttons by reading
-    the 'test mode status' (0x20) register:
+2. For FSP version < STL3888 Cx, determine number of buttons by reading
+   the 'test mode status' (0x20) register::
 
 	buttons = reg[0x20] & 0x30
 
@@ -476,25 +503,24 @@ http://www.computer-engineering.org/ps2mouse/
 		Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse'
 		section A for packet parsing detail
 
-2b. For FSP version >= STL3888 Cx:
+3. For FSP version >= STL3888 Cx:
 	Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse'
 	section A for packet parsing detail (ignore byte 4, bit ~ 7)
 
-==============================================================================
-* Programming Sequence for Register Reading/Writing
-==============================================================================
+Programming Sequence for Register Reading/Writing
+=================================================
 
 Register inversion requirement:
 
-  Following values needed to be inverted(the '~' operator in C) before being
-sent to FSP:
+Following values needed to be inverted(the '~' operator in C) before being
+sent to FSP::
 
 	0xe8, 0xe9, 0xee, 0xf2, 0xf3 and 0xff.
 
 Register swapping requirement:
 
-  Following values needed to have their higher 4 bits and lower 4 bits being
-swapped before being sent to FSP:
+Following values needed to have their higher 4 bits and lower 4 bits being
+swapped before being sent to FSP::
 
 	10, 20, 40, 60, 80, 100 and 200.
 
@@ -512,33 +538,33 @@ Register reading sequence:
 	inverted(refer to the 'Register inversion requirement' section),
 	goto step 6
 
-	5a. send 0x68 PS/2 command to FSP;
+	  a. send 0x68 PS/2 command to FSP;
 
-	5b. send the inverted register address to FSP and goto step 8;
+	  b. send the inverted register address to FSP and goto step 8;
 
 	6. if the register address being to read is not required to be
 	swapped(refer to the 'Register swapping requirement' section),
 	goto step 7
 
-	6a. send 0xcc PS/2 command to FSP;
+	  a. send 0xcc PS/2 command to FSP;
 
-	6b. send the swapped register address to FSP and goto step 8;
+	  b. send the swapped register address to FSP and goto step 8;
 
 	7. send 0x66 PS/2 command to FSP;
 
-	7a. send the original register address to FSP and goto step 8;
+	  a. send the original register address to FSP and goto step 8;
 
 	8. send 0xe9(status request) PS/2 command to FSP;
 
 	9. the 4th byte of the response read from FSP should be the
-	requested register value(?? indicates don't care byte):
+	requested register value(?? indicates don't care byte)::
 
 		host: 0xe9
 		3888: 0xfa (??) (??) (val)
 
 	* Note that since the Cx release, the hardware will return 1's
-	complement of the register value at the 3rd byte of status request
-	result:
+	  complement of the register value at the 3rd byte of status request
+	  result::
 
 		host: 0xe9
 		3888: 0xfa (??) (~val) (val)
@@ -551,21 +577,21 @@ Register writing sequence:
 	inverted(refer to the 'Register inversion requirement' section),
 	goto step 3
 
-	2a. send 0x74 PS/2 command to FSP;
+	  a. send 0x74 PS/2 command to FSP;
 
-	2b. send the inverted register address to FSP and goto step 5;
+	  b. send the inverted register address to FSP and goto step 5;
 
 	3. if the register address being to write is not required to be
 	swapped(refer to the 'Register swapping requirement' section),
 	goto step 4
 
-	3a. send 0x77 PS/2 command to FSP;
+	  a. send 0x77 PS/2 command to FSP;
 
-	3b. send the swapped register address to FSP and goto step 5;
+	  b. send the swapped register address to FSP and goto step 5;
 
 	4. send 0x55 PS/2 command to FSP;
 
-	4a. send the register address to FSP and goto step 5;
+	  a. send the register address to FSP and goto step 5;
 
 	5. send 0xf3 PS/2 command to FSP;
 
@@ -573,43 +599,42 @@ Register writing sequence:
 	inverted(refer to the 'Register inversion requirement' section),
 	goto step 7
 
-	6a. send 0x47 PS/2 command to FSP;
+	  a. send 0x47 PS/2 command to FSP;
 
-	6b. send the inverted register value to FSP and goto step 9;
+	  b. send the inverted register value to FSP and goto step 9;
 
 	7. if the register value being to write is not required to be
 	swapped(refer to the 'Register swapping requirement' section),
 	goto step 8
 
-	7a. send 0x44 PS/2 command to FSP;
+	  a. send 0x44 PS/2 command to FSP;
 
-	7b. send the swapped register value to FSP and goto step 9;
+	  b. send the swapped register value to FSP and goto step 9;
 
 	8. send 0x33 PS/2 command to FSP;
 
-	8a. send the register value to FSP;
+	  a. send the register value to FSP;
 
 	9. the register writing sequence is completed.
 
-	* Note that since the Cx release, the hardware will return 1's
-	complement of the register value at the 3rd byte of status request
-	result. Host can optionally send another 0xe9 (status request) PS/2
-	command to FSP at the end of register writing to verify that the
-	register writing operation is successful (?? indicates don't care
-	byte):
+	* Since the Cx release, the hardware will return 1's
+	  complement of the register value at the 3rd byte of status request
+	  result. Host can optionally send another 0xe9 (status request) PS/2
+	  command to FSP at the end of register writing to verify that the
+	  register writing operation is successful (?? indicates don't care
+	  byte)::
 
 		host: 0xe9
 		3888: 0xfa (??) (~val) (val)
 
-==============================================================================
-* Programming Sequence for Page Register Reading/Writing
-==============================================================================
+Programming Sequence for Page Register Reading/Writing
+======================================================
 
-  In order to overcome the limitation of maximum number of registers
+In order to overcome the limitation of maximum number of registers
 supported, the hardware separates register into different groups called
 'pages.' Each page is able to include up to 255 registers.
 
-  The default page after power up is 0x82; therefore, if one has to get
+The default page after power up is 0x82; therefore, if one has to get
 access to register 0x8301, one has to use following sequence to switch
 to page 0x83, then start reading/writing from/to offset 0x01 by using
 the register read/write sequence described in previous section.
@@ -632,6 +657,7 @@ Page register reading sequence:
 
 	8. the response read from FSP should be the requested page value.
 
+
 Page register writing sequence:
 
 	1. send 0xf3 PS/2 command to FSP;
@@ -646,17 +672,17 @@ Page register writing sequence:
 	inverted(refer to the 'Register inversion requirement' section),
 	goto step 6
 
-	5a. send 0x47 PS/2 command to FSP;
+	  a. send 0x47 PS/2 command to FSP;
 
-	5b. send the inverted page address to FSP and goto step 9;
+	  b. send the inverted page address to FSP and goto step 9;
 
 	6. if the page address being written is not required to be
 	swapped(refer to the 'Register swapping requirement' section),
 	goto step 7
 
-	6a. send 0x44 PS/2 command to FSP;
+	  a. send 0x44 PS/2 command to FSP;
 
-	6b. send the swapped page address to FSP and goto step 9;
+	  b. send the swapped page address to FSP and goto step 9;
 
 	7. send 0x33 PS/2 command to FSP;
 
@@ -664,16 +690,17 @@ Page register writing sequence:
 
 	9. the page register writing sequence is completed.
 
-==============================================================================
-* Gesture ID
-==============================================================================
+Gesture ID
+==========
 
-  Unlike other devices which sends multiple fingers' coordinates to host,
+Unlike other devices which sends multiple fingers' coordinates to host,
 FSP processes multiple fingers' coordinates internally and convert them
 into a 8 bits integer, namely 'Gesture ID.'  Following is a list of
 supported gesture IDs:
 
+	======= ==================================
 	ID	Description
+	======= ==================================
 	0x86	2 finger straight up
 	0x82	2 finger straight down
 	0x80	2 finger straight right
@@ -687,38 +714,38 @@ supported gesture IDs:
 	0x28	3 finger straight right
 	0x2c	3 finger straight left
 	0x38	palm
+	======= ==================================
 
-==============================================================================
-* Register Listing
-==============================================================================
+Register Listing
+================
 
-  Registers are represented in 16 bits values. The higher 8 bits represent
+Registers are represented in 16 bits values. The higher 8 bits represent
 the page address and the lower 8 bits represent the relative offset within
 that particular page.  Refer to the 'Programming Sequence for Page Register
 Reading/Writing' section for instructions on how to change current page
-address.
+address::
 
-offset	width		default	r/w	name
-0x8200	bit7~bit0	0x01	RO	device ID
+ offset	width		default	r/w	name
+ 0x8200	bit7~bit0	0x01	RO	device ID
 
-0x8201	bit7~bit0		RW	version ID
+ 0x8201	bit7~bit0		RW	version ID
 					0xc1: STL3888 Ax
 					0xd0 ~ 0xd2: STL3888 Bx
 					0xe0 ~ 0xe1: STL3888 Cx
 					0xe2 ~ 0xe3: STL3888 Dx
 
-0x8202	bit7~bit0	0x01	RO	vendor ID
+ 0x8202	bit7~bit0	0x01	RO	vendor ID
 
-0x8203	bit7~bit0	0x01	RO	product ID
+ 0x8203	bit7~bit0	0x01	RO	product ID
 
-0x8204	bit3~bit0	0x01	RW	revision ID
+ 0x8204	bit3~bit0	0x01	RW	revision ID
 
-0x820b					test mode status 1
+ 0x820b					test mode status 1
 	bit3		1	RO	0: rotate 180 degree
 					1: no rotation
 					*only supported by H/W prior to Cx
 
-0x820f					register file page control
+ 0x820f					register file page control
 	bit2		0	RW	1: rotate 180 degree
 					0: no rotation
 					*supported since Cx
@@ -726,7 +753,7 @@ offset	width		default	r/w	name
 	bit0		0	RW	1 to enable page 1 register files
 					*only supported by H/W prior to Cx
 
-0x8210				RW	system control 1
+ 0x8210				RW	system control 1
 	bit0		1	RW	Reserved, must be 1
 	bit1		0	RW	Reserved, must be 0
 	bit4		0	RW	Reserved, must be 0
@@ -737,7 +764,7 @@ offset	width		default	r/w	name
 	40 41 42 43.  In addition to that, this bit must be 1 when gesture
 	mode is enabled)
 
-0x8220					test mode status
+ 0x8220					test mode status
 	bit5~bit4		RO	number of buttons
 					11 => 2, lbtn/rbtn
 					10 => 4, lbtn/rbtn/scru/scrd
@@ -745,13 +772,13 @@ offset	width		default	r/w	name
 					00 => 6, lbtn/rbtn/scru/scrd/fbtn/bbtn
 					*only supported by H/W prior to Cx
 
-0x8231				RW	on-pad command detection
+ 0x8231				RW	on-pad command detection
 	bit7		0	RW	on-pad command left button down tag
 					enable
 					0: disable, 1: enable
 					*only supported by H/W prior to Cx
 
-0x8234				RW	on-pad command control 5
+ 0x8234				RW	on-pad command control 5
 	bit4~bit0	0x05	RW	XLO in 0s/4/1, so 03h = 0010.1b = 2.5
 	(Note that position unit is in 0.5 scanline)
 					*only supported by H/W prior to Cx
@@ -760,22 +787,22 @@ offset	width		default	r/w	name
 					0: disable, 1: enable
 					*only supported by H/W prior to Cx
 
-0x8235				RW	on-pad command control 6
+ 0x8235				RW	on-pad command control 6
 	bit4~bit0	0x1d	RW	XHI in 0s/4/1, so 19h = 1100.1b = 12.5
 	(Note that position unit is in 0.5 scanline)
 					*only supported by H/W prior to Cx
 
-0x8236				RW	on-pad command control 7
+ 0x8236				RW	on-pad command control 7
 	bit4~bit0	0x04	RW	YLO in 0s/4/1, so 03h = 0010.1b = 2.5
 	(Note that position unit is in 0.5 scanline)
 					*only supported by H/W prior to Cx
 
-0x8237				RW	on-pad command control 8
+ 0x8237				RW	on-pad command control 8
 	bit4~bit0	0x13	RW	YHI in 0s/4/1, so 11h = 1000.1b = 8.5
 	(Note that position unit is in 0.5 scanline)
 					*only supported by H/W prior to Cx
 
-0x8240				RW	system control 5
+ 0x8240				RW	system control 5
 	bit1		0	RW	FSP Intellimouse mode enable
 					0: disable, 1: enable
 					*only supported by H/W prior to Cx
@@ -813,7 +840,7 @@ offset	width		default	r/w	name
 					0: disable, 1: enable
 					*only supported by H/W prior to Cx
 
-0x8243				RW	on-pad control
+ 0x8243				RW	on-pad control
 	bit0		0	RW	on-pad control enable
 					0: disable, 1: enable
 	(Note that if this bit is cleared, bit 3/5 will be ineffective)
@@ -827,7 +854,7 @@ offset	width		default	r/w	name
 					0: disable, 1: enable
 					*only supported by H/W prior to Cx
 
-0x8290				RW	software control register 1
+ 0x8290				RW	software control register 1
 	bit0		0	RW	absolute coordination mode
 					0: disable, 1: enable
 					*supported since Cx
@@ -856,16 +883,17 @@ offset	width		default	r/w	name
 					*supported since Cx
 
 	bit7		0	RW	Bx packet output compatible mode
-					0: disable, 1: enable					*supported since Cx
+					0: disable, 1: enable
+					*supported since Cx
 					*supported since Cx
 
 
-0x833d				RW	on-pad command control 1
+ 0x833d				RW	on-pad command control 1
 	bit7		1	RW	on-pad command detection enable
 					0: disable, 1: enable
 					*supported since Cx
 
-0x833e				RW	on-pad command detection
+ 0x833e				RW	on-pad command detection
 	bit7		0	RW	on-pad command left button down tag
 					enable. Works only in H/W based PS/2
 					data packet mode.
-- 
2.9.3

[PATCH v2 26/37] docs: input/userio: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/userio.txt | 79 +++++++++++++++++++++++++-----------------
 1 file changed, 47 insertions(+), 32 deletions(-)

diff --git a/Documentation/input/userio.txt b/Documentation/input/userio.txt
index 0880c0f447a6..f780c77931fe 100644
--- a/Documentation/input/userio.txt
+++ b/Documentation/input/userio.txt
@@ -1,37 +1,47 @@
-			      The userio Protocol
-	     (c) 2015 Stephen Chandler Paul <thatslyude@gmail.com>
-			      Sponsored by Red Hat
---------------------------------------------------------------------------------
-
-1. Introduction
-~~~~~~~~~~~~~~~
-  This module is intended to try to make the lives of input driver developers
+.. include:: <isonum.txt>
+
+===================
+The userio Protocol
+===================
+
+
+:Copyright: |copy| 2015 Stephen Chandler Paul <thatslyude@gmail.com>
+
+Sponsored by Red Hat
+
+
+Introduction
+=============
+
+This module is intended to try to make the lives of input driver developers
 easier by allowing them to test various serio devices (mainly the various
 touchpads found on laptops) without having to have the physical device in front
 of them. userio accomplishes this by allowing any privileged userspace program
 to directly interact with the kernel's serio driver and control a virtual serio
 port from there.
 
-2. Usage overview
-~~~~~~~~~~~~~~~~~
-  In order to interact with the userio kernel module, one simply opens the
+Usage overview
+==============
+
+In order to interact with the userio kernel module, one simply opens the
 /dev/userio character device in their applications. Commands are sent to the
 kernel module by writing to the device, and any data received from the serio
 driver is read as-is from the /dev/userio device. All of the structures and
 macros you need to interact with the device are defined in <linux/userio.h> and
 <linux/serio.h>.
 
-3. Command Structure
-~~~~~~~~~~~~~~~~~~~~
-  The struct used for sending commands to /dev/userio is as follows:
+Command Structure
+=================
+
+The struct used for sending commands to /dev/userio is as follows::
 
 	struct userio_cmd {
 		__u8 type;
 		__u8 data;
 	};
 
-  "type" describes the type of command that is being sent. This can be any one
-of the USERIO_CMD macros defined in <linux/userio.h>. "data" is the argument
+``type`` describes the type of command that is being sent. This can be any one
+of the USERIO_CMD macros defined in <linux/userio.h>. ``data`` is the argument
 that goes along with the command. In the event that the command doesn't have an
 argument, this field can be left untouched and will be ignored by the kernel.
 Each command should be sent by writing the struct directly to the character
@@ -39,31 +49,36 @@ device. In the event that the command you send is invalid, an error will be
 returned by the character device and a more descriptive error will be printed
 to the kernel log. Only one command can be sent at a time, any additional data
 written to the character device after the initial command will be ignored.
-  To close the virtual serio port, just close /dev/userio.
 
-4. Commands
-~~~~~~~~~~~
+To close the virtual serio port, just close /dev/userio.
 
-4.1 USERIO_CMD_REGISTER
-~~~~~~~~~~~~~~~~~~~~~~~
-  Registers the port with the serio driver and begins transmitting data back and
+Commands
+========
+
+USERIO_CMD_REGISTER
+~~~~~~~~~~~~~~~~~~~
+
+Registers the port with the serio driver and begins transmitting data back and
 forth. Registration can only be performed once a port type is set with
 USERIO_CMD_SET_PORT_TYPE. Has no argument.
 
-4.2 USERIO_CMD_SET_PORT_TYPE
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  Sets the type of port we're emulating, where "data" is the port type being
+USERIO_CMD_SET_PORT_TYPE
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sets the type of port we're emulating, where ``data`` is the port type being
 set. Can be any of the macros from <linux/serio.h>. For example: SERIO_8042
 would set the port type to be a normal PS/2 port.
 
-4.3 USERIO_CMD_SEND_INTERRUPT
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  Sends an interrupt through the virtual serio port to the serio driver, where
-"data" is the interrupt data being sent.
+USERIO_CMD_SEND_INTERRUPT
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-5. Userspace tools
-~~~~~~~~~~~~~~~~~~
-  The userio userspace tools are able to record PS/2 devices using some of the
+Sends an interrupt through the virtual serio port to the serio driver, where
+``data`` is the interrupt data being sent.
+
+Userspace tools
+===============
+
+The userio userspace tools are able to record PS/2 devices using some of the
 debugging information from i8042, and play back the devices on /dev/userio. The
 latest version of these tools can be found at:
 
-- 
2.9.3

[PATCH v2 27/37] docs: input/walkera0701: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/walkera0701.txt | 53 +++++++++++++++++++++++++------------
 1 file changed, 36 insertions(+), 17 deletions(-)

diff --git a/Documentation/input/walkera0701.txt b/Documentation/input/walkera0701.txt
index 49e3ac60dcef..2adda99ca717 100644
--- a/Documentation/input/walkera0701.txt
+++ b/Documentation/input/walkera0701.txt
@@ -1,3 +1,6 @@
+===========================
+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:
-                   (ANALOG)
-    SYNC      BIN   OCT
-  +---------+      +------+
-  |         |      |      |
---+         +------+      +---
-
-Frame:
+Signal pulses
+-------------
+
+::
+
+                     (ANALOG)
+      SYNC      BIN   OCT
+    +---------+      +------+
+    |         |      |      |
+  --+         +------+      +---
+
+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.
-
-- 
2.9.3

[PATCH v2 28/37] docs: input/xpad: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/xpad.txt | 120 ++++++++++++++++++++++++-------------------
 1 file changed, 68 insertions(+), 52 deletions(-)

diff --git a/Documentation/input/xpad.txt b/Documentation/input/xpad.txt
index d1b23f295db4..0bae002cf17a 100644
--- a/Documentation/input/xpad.txt
+++ b/Documentation/input/xpad.txt
@@ -1,4 +1,6 @@
+=======================================================
 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,8 +79,9 @@ 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.
 
@@ -88,9 +95,11 @@ to the list of supported devices, ensuring that it will work out of the
 box in the future.
 
 
-1. USB adapters
---------------
+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 +110,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.
@@ -123,8 +133,8 @@ 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
@@ -132,13 +142,15 @@ the xpad module should be auto loaded. To confirm you can cat
 
 
 
-3. Supported Controllers
-------------------------
+Supported Controllers
+=====================
+
 For a full list of supported controllers and associated vendor and product
 IDs see the xpad_device[] array[6].
 
 As of the historic version 0.0.6 (2006-10-10) the following devices
-were supported:
+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 +164,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,57 +184,59 @@ 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.
- 
+    http://euc.jp/periphs/xbox-controller.ja.html.
+
 His useful info and both the usb-skeleton as well as the iforce input driver
 (Greg Kroah-Hartmann; Vojtech Pavlik) helped a lot in rapid prototyping
 the basic functionality.
 
 
 
-6. References
--------------
+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
+[4]: /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany)::
 
-[5]: /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US):
+    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
 
-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
+[5]: /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US)::
+
+    T:  Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12  MxCh= 0
+    D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
+    P:  Vendor=0c12 ProdID=8809 Rev= 0.01
+    S:  Product=XBOX DDR
+    C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
+    I:  If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad
+    E:  Ad=82(I) Atr=03(Int.) MxPS=  32 Ivl=4ms
+    E:  Ad=02(O) Atr=03(Int.) MxPS=  32 Ivl=4ms
 
 [6]: http://lxr.free-electrons.com/ident?i=xpad_device
 
 
 
-7. Historic Edits
------------------
-Marko Friedemann <mfr@bmx-chemnitz.de>
-2002-07-16
+Historic Edits
+==============
+
+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'
-- 
2.9.3

[PATCH v2 29/37] docs: input/yealink: convert it to ReST format

[Mauro Carvalho Chehab]

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/yealink.txt | 164 +++++++++++++++++++++++-----------------
 1 file changed, 93 insertions(+), 71 deletions(-)

diff --git a/Documentation/input/yealink.txt b/Documentation/input/yealink.txt
index 8277b76ec506..b231d8baf4bb 100644
--- a/Documentation/input/yealink.txt
+++ b/Documentation/input/yealink.txt
@@ -1,8 +1,12 @@
+===============================================
 Driver documentation for yealink usb-p1k phones
+===============================================
+
+Status
+======
 
-0. Status
-~~~~~~~~~
 The p1k is a relatively cheap usb 1.1 phone with:
+
   - keyboard		full support, yealink.ko / input event API
   - LCD			full support, yealink.ko / sysfs API
   - LED			full support, yealink.ko / sysfs API
@@ -14,10 +18,11 @@ The p1k is a relatively cheap usb 1.1 phone with:
 For vendor documentation see http://www.yealink.com
 
 
-1. Compilation (stand alone version)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Compilation (stand alone version)
+=================================
+
 Currently only kernel 2.6.x.y versions are supported.
-In order to build the yealink.ko module do
+In order to build the yealink.ko module do::
 
   make
 
@@ -26,26 +31,28 @@ the Makefile is pointing to the location where your kernel sources
 are located, default /usr/src/linux.
 
 
-1.1 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.
+Troubleshooting
+~~~~~~~~~~~~~~~
 
-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.
+: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
+=================
 
-2. keyboard features
-~~~~~~~~~~~~~~~~~~~~
 The current mapping in the kernel is provided by the map_p1k_to_key
-function:
+function::
 
    Physical USB-P1K button layout	input events
 
@@ -60,14 +67,15 @@ function:
         7      8      9			7, 8, 9,
         *      0      #			*, 0, #,
 
-  The "up" and "down" keys, are symbolised by arrows on the button.
-  The "pickup" and "hangup" keys are symbolised by a green and red phone
-  on the button.
+The "up" and "down" keys, are symbolised by arrows on the button.
+The "pickup" and "hangup" keys are symbolised by a green and red phone
+on the button.
 
 
-3. LCD features
-~~~~~~~~~~~~~~~
-The LCD is divided and organised as a 3 line display:
+LCD features
+============
+
+The LCD is divided and organised as a 3 line display::
 
     |[]   [][]   [][]   [][]   in   |[][]
     |[] M [][] D [][] : [][]   out  |[][]
@@ -79,18 +87,19 @@ The LCD is divided and organised as a 3 line display:
     [] [] [] [] [] [] [] [] [] [] [] []
 
 
-Line 1	Format (see below)	: 18.e8.M8.88...188
-	Icon names		:   M  D  :  IN OUT STORE
-Line 2  Format			: .........
-	Icon name		: NEW REP SU MO TU WE TH FR SA
-Line 3  Format			: 888888888888
+  Line 1  Format (see below)	: 18.e8.M8.88...188
+	  Icon names		:   M  D  :  IN OUT STORE
+  Line 2  Format		: .........
+	  Icon name		: NEW REP SU MO TU WE TH FR SA
+  Line 3  Format		: 888888888888
 
 
 Format description:
   From a userspace perspective the world is separated into "digits" and "icons".
   A digit can have a character set, an icon can only be ON or OFF.
 
-  Format specifier
+  Format specifier::
+
     '8' :  Generic 7 segment digit with individual addressable segments
 
     Reduced capability 7 segment digit, when segments are hard wired together.
@@ -105,9 +114,11 @@ Format description:
 	  elements.
 
 
-4. Driver usage
-~~~~~~~~~~~~~~~
-For userland the following interfaces are available using the sysfs interface:
+Driver usage
+============
+
+For userland the following interfaces are available using the sysfs interface::
+
   /sys/.../
            line1	Read/Write, lcd line1
            line2	Read/Write, lcd line2
@@ -118,38 +129,43 @@ For userland the following interfaces are available using the sysfs interface:
 	   show_icon    Write, display the element by writing the icon name.
 
 	   map_seg7	Read/Write, the 7 segments char set, common for all
-	   		yealink phones. (see map_to_7segment.h)
+			yealink phones. (see map_to_7segment.h)
 
 	   ringtone	Write, upload binary representation of a ringtone,
-	   		see yealink.c. status EXPERIMENTAL due to potential
+			see yealink.c. status EXPERIMENTAL due to potential
 			races between async. and sync usb calls.
 
 
-4.1 lineX
-~~~~~~~~~
-Reading /sys/../lineX will return the format string with its current value:
+lineX
+~~~~~
 
-  Example:
-  cat ./line3
-  888888888888
-  Linux Rocks!
+Reading /sys/../lineX will return the format string with its current value.
+
+  Example::
+
+    cat ./line3
+    888888888888
+    Linux Rocks!
 
 Writing to /sys/../lineX will set the corresponding LCD line.
+
  - Excess characters are ignored.
  - If less characters are written than allowed, the remaining digits are
    unchanged.
  - The tab '\t'and '\n' char does not overwrite the original content.
  - Writing a space to an icon will always hide its content.
 
-  Example:
-  date +"%m.%e.%k:%M"  | sed 's/^0/ /' > ./line1
+  Example::
+
+    date +"%m.%e.%k:%M"  | sed 's/^0/ /' > ./line1
 
   Will update the LCD with the current date & time.
 
 
-4.2 get_icons
-~~~~~~~~~~~~~
-Reading will return all available icon names and its current settings:
+get_icons
+~~~~~~~~~
+
+Reading will return all available icon names and its current settings::
 
   cat ./get_icons
   on M
@@ -172,45 +188,51 @@ Reading will return all available icon names and its current settings:
      RINGTONE
 
 
-4.3 show/hide icons
-~~~~~~~~~~~~~~~~~~~
+show/hide icons
+~~~~~~~~~~~~~~~
+
 Writing to these files will update the state of the icon.
 Only one icon at a time can be updated.
 
 If an icon is also on a ./lineX the corresponding value is
 updated with the first letter of the icon.
 
-  Example - light up the store icon:
-  echo -n "STORE" > ./show_icon
+  Example - light up the store icon::
 
-  cat ./line1
-  18.e8.M8.88...188
-               S
+    echo -n "STORE" > ./show_icon
 
-  Example - sound the ringtone for 10 seconds:
-  echo -n RINGTONE > /sys/..../show_icon
-  sleep 10
-  echo -n RINGTONE > /sys/..../hide_icon
+    cat ./line1
+    18.e8.M8.88...188
+		  S
 
+  Example - sound the ringtone for 10 seconds::
+
+    echo -n RINGTONE > /sys/..../show_icon
+    sleep 10
+    echo -n RINGTONE > /sys/..../hide_icon
+
+
+Sound features
+==============
 
-5. Sound features
-~~~~~~~~~~~~~~~~~
 Sound is supported by the ALSA driver: snd_usb_audio
 
 One 16-bit channel with sample and playback rates of 8000 Hz is the practical
 limit of the device.
 
-  Example - recording test:
-  arecord -v -d 10 -r 8000 -f S16_LE -t wav  foobar.wav
+  Example - recording test::
 
-  Example - playback test:
-  aplay foobar.wav
+    arecord -v -d 10 -r 8000 -f S16_LE -t wav  foobar.wav
 
+  Example - playback test::
+
+    aplay foobar.wav
+
+
+Credits & Acknowledgments
+=========================
 
-6. Credits & Acknowledgments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   - Olivier Vandorpe, for starting the usbb2k-api project doing much of
-	the reverse engineering.
+    the reverse engineering.
   - Martin Diehl, for pointing out how to handle USB memory allocation.
   - Dmitry Torokhov, for the numerous code reviews and suggestions.
-
-- 
2.9.3

[PATCH v2 30/37] docs-rst: create a book with Linux Input documentation

[Mauro Carvalho Chehab]

Now that all files under Documentation/input follows the
ReST markup language, rename them to *.rst and create a
book for the Linux Input subsystem.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/conf.py                              |  2 +
 Documentation/input/{alps.txt => alps.rst}         |  0
 Documentation/input/{amijoy.txt => amijoy.rst}     |  0
 .../input/{appletouch.txt => appletouch.rst}       |  0
 Documentation/input/{atarikbd.txt => atarikbd.rst} |  0
 Documentation/input/{bcm5974.txt => bcm5974.rst}   |  0
 Documentation/input/{cd32.txt => cd32.rst}         |  0
 .../input/{cma3000_d0x.txt => cma3000_d0x.rst}     |  0
 Documentation/input/conf.py                        | 10 +++
 Documentation/input/{cs461x.txt => cs461x.rst}     |  0
 .../input/{edt-ft5x06.txt => edt-ft5x06.rst}       |  0
 Documentation/input/{elantech.txt => elantech.rst} |  0
 .../input/{event-codes.txt => event-codes.rst}     |  0
 Documentation/input/{ff.txt => ff.rst}             |  0
 Documentation/input/{gamepad.txt => gamepad.rst}   |  0
 ...rt-programming.txt => gameport-programming.rst} |  0
 .../input/{gpio-tilt.txt => gpio-tilt.rst}         |  0
 .../{iforce-protocol.txt => iforce-protocol.rst}   |  0
 Documentation/input/index.rst                      | 77 ++++++++++++++++++++++
 ...input-programming.txt => input-programming.rst} |  0
 Documentation/input/{input.txt => input.rst}       | 20 ------
 .../input/{joystick-api.txt => joystick-api.rst}   |  0
 .../{joystick-parport.txt => joystick-parport.rst} |  0
 Documentation/input/{joystick.txt => joystick.rst} |  0
 ...touch-protocol.txt => multi-touch-protocol.rst} |  0
 Documentation/input/{notifier.txt => notifier.rst} |  0
 Documentation/input/{ntrig.txt => ntrig.rst}       |  0
 .../{rotary-encoder.txt => rotary-encoder.rst}     |  0
 Documentation/input/{sentelic.txt => sentelic.rst} |  0
 Documentation/input/{userio.txt => userio.rst}     |  0
 .../input/{walkera0701.txt => walkera0701.rst}     |  0
 Documentation/input/{xpad.txt => xpad.rst}         |  0
 Documentation/input/{yealink.txt => yealink.rst}   |  0
 33 files changed, 89 insertions(+), 20 deletions(-)
 rename Documentation/input/{alps.txt => alps.rst} (100%)
 rename Documentation/input/{amijoy.txt => amijoy.rst} (100%)
 rename Documentation/input/{appletouch.txt => appletouch.rst} (100%)
 rename Documentation/input/{atarikbd.txt => atarikbd.rst} (100%)
 rename Documentation/input/{bcm5974.txt => bcm5974.rst} (100%)
 rename Documentation/input/{cd32.txt => cd32.rst} (100%)
 rename Documentation/input/{cma3000_d0x.txt => cma3000_d0x.rst} (100%)
 create mode 100644 Documentation/input/conf.py
 rename Documentation/input/{cs461x.txt => cs461x.rst} (100%)
 rename Documentation/input/{edt-ft5x06.txt => edt-ft5x06.rst} (100%)
 rename Documentation/input/{elantech.txt => elantech.rst} (100%)
 rename Documentation/input/{event-codes.txt => event-codes.rst} (100%)
 rename Documentation/input/{ff.txt => ff.rst} (100%)
 rename Documentation/input/{gamepad.txt => gamepad.rst} (100%)
 rename Documentation/input/{gameport-programming.txt => gameport-programming.rst} (100%)
 rename Documentation/input/{gpio-tilt.txt => gpio-tilt.rst} (100%)
 rename Documentation/input/{iforce-protocol.txt => iforce-protocol.rst} (100%)
 create mode 100644 Documentation/input/index.rst
 rename Documentation/input/{input-programming.txt => input-programming.rst} (100%)
 rename Documentation/input/{input.txt => input.rst} (92%)
 rename Documentation/input/{joystick-api.txt => joystick-api.rst} (100%)
 rename Documentation/input/{joystick-parport.txt => joystick-parport.rst} (100%)
 rename Documentation/input/{joystick.txt => joystick.rst} (100%)
 rename Documentation/input/{multi-touch-protocol.txt => multi-touch-protocol.rst} (100%)
 rename Documentation/input/{notifier.txt => notifier.rst} (100%)
 rename Documentation/input/{ntrig.txt => ntrig.rst} (100%)
 rename Documentation/input/{rotary-encoder.txt => rotary-encoder.rst} (100%)
 rename Documentation/input/{sentelic.txt => sentelic.rst} (100%)
 rename Documentation/input/{userio.txt => userio.rst} (100%)
 rename Documentation/input/{walkera0701.txt => walkera0701.rst} (100%)
 rename Documentation/input/{xpad.txt => xpad.rst} (100%)
 rename Documentation/input/{yealink.txt => yealink.rst} (100%)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 7fadb3b83293..fef209edb4d7 100644
--- a/Documentation/conf.py
+++ b/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',
diff --git a/Documentation/input/alps.txt b/Documentation/input/alps.rst
similarity index 100%
rename from Documentation/input/alps.txt
rename to Documentation/input/alps.rst
diff --git a/Documentation/input/amijoy.txt b/Documentation/input/amijoy.rst
similarity index 100%
rename from Documentation/input/amijoy.txt
rename to Documentation/input/amijoy.rst
diff --git a/Documentation/input/appletouch.txt b/Documentation/input/appletouch.rst
similarity index 100%
rename from Documentation/input/appletouch.txt
rename to Documentation/input/appletouch.rst
diff --git a/Documentation/input/atarikbd.txt b/Documentation/input/atarikbd.rst
similarity index 100%
rename from Documentation/input/atarikbd.txt
rename to Documentation/input/atarikbd.rst
diff --git a/Documentation/input/bcm5974.txt b/Documentation/input/bcm5974.rst
similarity index 100%
rename from Documentation/input/bcm5974.txt
rename to Documentation/input/bcm5974.rst
diff --git a/Documentation/input/cd32.txt b/Documentation/input/cd32.rst
similarity index 100%
rename from Documentation/input/cd32.txt
rename to Documentation/input/cd32.rst
diff --git a/Documentation/input/cma3000_d0x.txt b/Documentation/input/cma3000_d0x.rst
similarity index 100%
rename from Documentation/input/cma3000_d0x.txt
rename to Documentation/input/cma3000_d0x.rst
diff --git a/Documentation/input/conf.py b/Documentation/input/conf.py
new file mode 100644
index 000000000000..d2352fdc92ed
--- /dev/null
+++ b/Documentation/input/conf.py
@@ -0,0 +1,10 @@
+# -*- 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'),
+]
diff --git a/Documentation/input/cs461x.txt b/Documentation/input/cs461x.rst
similarity index 100%
rename from Documentation/input/cs461x.txt
rename to Documentation/input/cs461x.rst
diff --git a/Documentation/input/edt-ft5x06.txt b/Documentation/input/edt-ft5x06.rst
similarity index 100%
rename from Documentation/input/edt-ft5x06.txt
rename to Documentation/input/edt-ft5x06.rst
diff --git a/Documentation/input/elantech.txt b/Documentation/input/elantech.rst
similarity index 100%
rename from Documentation/input/elantech.txt
rename to Documentation/input/elantech.rst
diff --git a/Documentation/input/event-codes.txt b/Documentation/input/event-codes.rst
similarity index 100%
rename from Documentation/input/event-codes.txt
rename to Documentation/input/event-codes.rst
diff --git a/Documentation/input/ff.txt b/Documentation/input/ff.rst
similarity index 100%
rename from Documentation/input/ff.txt
rename to Documentation/input/ff.rst
diff --git a/Documentation/input/gamepad.txt b/Documentation/input/gamepad.rst
similarity index 100%
rename from Documentation/input/gamepad.txt
rename to Documentation/input/gamepad.rst
diff --git a/Documentation/input/gameport-programming.txt b/Documentation/input/gameport-programming.rst
similarity index 100%
rename from Documentation/input/gameport-programming.txt
rename to Documentation/input/gameport-programming.rst
diff --git a/Documentation/input/gpio-tilt.txt b/Documentation/input/gpio-tilt.rst
similarity index 100%
rename from Documentation/input/gpio-tilt.txt
rename to Documentation/input/gpio-tilt.rst
diff --git a/Documentation/input/iforce-protocol.txt b/Documentation/input/iforce-protocol.rst
similarity index 100%
rename from Documentation/input/iforce-protocol.txt
rename to Documentation/input/iforce-protocol.rst
diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst
new file mode 100644
index 000000000000..153f0d476c3e
--- /dev/null
+++ b/Documentation/input/index.rst
@@ -0,0 +1,77 @@
+=============================
+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
+========
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   input
+   input-programming
+   event-codes
+   joystick
+   joystick-api
+   multi-touch-protocol
+   gamepad
+   gameport-programming
+   ff
+   notifier
+   userio
+
+Input drivers
+=============
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   alps
+   amijoy
+   appletouch
+   atarikbd
+   bcm5974
+   cd32
+   cma3000_d0x
+   cs461x
+   edt-ft5x06
+   elantech
+   iforce-protocol
+   joystick-parport
+   gpio-tilt
+   ntrig
+   rotary-encoder
+   sentelic
+   walkera0701
+   xpad
+   yealink
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/input/input-programming.txt b/Documentation/input/input-programming.rst
similarity index 100%
rename from Documentation/input/input-programming.txt
rename to Documentation/input/input-programming.rst
diff --git a/Documentation/input/input.txt b/Documentation/input/input.rst
similarity index 92%
rename from Documentation/input/input.txt
rename to Documentation/input/input.rst
index fda995e0ceb0..ac7669ad3e76 100644
--- a/Documentation/input/input.txt
+++ b/Documentation/input/input.rst
@@ -6,30 +6,10 @@ Linux Input drivers
 
 :Copyright: |copy| 1999-2001 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.
-
 Introduction
 ============
 
diff --git a/Documentation/input/joystick-api.txt b/Documentation/input/joystick-api.rst
similarity index 100%
rename from Documentation/input/joystick-api.txt
rename to Documentation/input/joystick-api.rst
diff --git a/Documentation/input/joystick-parport.txt b/Documentation/input/joystick-parport.rst
similarity index 100%
rename from Documentation/input/joystick-parport.txt
rename to Documentation/input/joystick-parport.rst
diff --git a/Documentation/input/joystick.txt b/Documentation/input/joystick.rst
similarity index 100%
rename from Documentation/input/joystick.txt
rename to Documentation/input/joystick.rst
diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.rst
similarity index 100%
rename from Documentation/input/multi-touch-protocol.txt
rename to Documentation/input/multi-touch-protocol.rst
diff --git a/Documentation/input/notifier.txt b/Documentation/input/notifier.rst
similarity index 100%
rename from Documentation/input/notifier.txt
rename to Documentation/input/notifier.rst
diff --git a/Documentation/input/ntrig.txt b/Documentation/input/ntrig.rst
similarity index 100%
rename from Documentation/input/ntrig.txt
rename to Documentation/input/ntrig.rst
diff --git a/Documentation/input/rotary-encoder.txt b/Documentation/input/rotary-encoder.rst
similarity index 100%
rename from Documentation/input/rotary-encoder.txt
rename to Documentation/input/rotary-encoder.rst
diff --git a/Documentation/input/sentelic.txt b/Documentation/input/sentelic.rst
similarity index 100%
rename from Documentation/input/sentelic.txt
rename to Documentation/input/sentelic.rst
diff --git a/Documentation/input/userio.txt b/Documentation/input/userio.rst
similarity index 100%
rename from Documentation/input/userio.txt
rename to Documentation/input/userio.rst
diff --git a/Documentation/input/walkera0701.txt b/Documentation/input/walkera0701.rst
similarity index 100%
rename from Documentation/input/walkera0701.txt
rename to Documentation/input/walkera0701.rst
diff --git a/Documentation/input/xpad.txt b/Documentation/input/xpad.rst
similarity index 100%
rename from Documentation/input/xpad.txt
rename to Documentation/input/xpad.rst
diff --git a/Documentation/input/yealink.txt b/Documentation/input/yealink.rst
similarity index 100%
rename from Documentation/input/yealink.txt
rename to Documentation/input/yealink.rst
-- 
2.9.3

[PATCH v2 31/37] docs: input/shape: convert it from xfig to svg

[Mauro Carvalho Chehab]

We're using svg as the standard format for vectorial images.

Convert it to .svg, in a way that it is easily editable.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/shape.fig | 65 -------------------------------------------
 Documentation/input/shape.svg | 39 ++++++++++++++++++++++++++
 2 files changed, 39 insertions(+), 65 deletions(-)
 delete mode 100644 Documentation/input/shape.fig
 create mode 100644 Documentation/input/shape.svg

diff --git a/Documentation/input/shape.fig b/Documentation/input/shape.fig
deleted file mode 100644
index c22bff83d06f..000000000000
--- a/Documentation/input/shape.fig
+++ /dev/null
@@ -1,65 +0,0 @@
-#FIG 3.2
-Landscape
-Center
-Inches
-Letter  
-100.00
-Single
--2
-1200 2
-2 1 0 2 0 7 50 0 -1 0.000 0 0 -1 0 0 6
-	 4200 3600 4200 3075 4950 2325 7425 2325 8250 3150 8250 3600
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 4200 3675 4200 5400
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 8250 3675 8250 5400
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 3675 3600 8700 3600
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 8775 3600 10200 3600
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 8325 3150 9075 3150
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 7500 2325 10200 2325
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 3600 3600 3000 3600
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 4125 3075 3000 3075
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2
-	0 0 1.00 60.00 120.00
-	0 0 1.00 60.00 120.00
-	 4200 5400 8175 5400
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2
-	0 0 1.00 60.00 120.00
-	0 0 1.00 60.00 120.00
-	 10125 2325 10125 3600
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2
-	0 0 1.00 60.00 120.00
-	0 0 1.00 60.00 120.00
-	 3000 3150 3000 3600
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2
-	0 0 1.00 60.00 120.00
-	0 0 1.00 60.00 120.00
-	 9075 3150 9075 3600
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 4950 2325 4950 1200
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 7425 2325 7425 1200
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4
-	 4200 3075 4200 2400 3600 1800 3600 1200
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4
-	 8250 3150 8250 2475 8775 1950 8775 1200
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2
-	0 0 1.00 60.00 120.00
-	0 0 1.00 60.00 120.00
-	 3600 1275 4950 1275
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2
-	0 0 1.00 60.00 120.00
-	0 0 1.00 60.00 120.00
-	 7425 1275 8700 1275
-4 1 0 50 0 0 12 0.0000 4 135 1140 6075 5325 Effect duration\001
-4 0 0 50 0 0 12 0.0000 4 180 1305 10200 3000 Effect magnitude\001
-4 0 0 50 0 0 12 0.0000 4 135 780 9150 3450 Fade level\001
-4 1 0 50 0 0 12 0.0000 4 180 1035 4275 1200 Attack length\001
-4 1 0 50 0 0 12 0.0000 4 180 885 8175 1200 Fade length\001
-4 2 0 50 0 0 12 0.0000 4 135 930 2925 3375 Attack level\001
diff --git a/Documentation/input/shape.svg b/Documentation/input/shape.svg
new file mode 100644
index 000000000000..fc0af44db3f7
--- /dev/null
+++ b/Documentation/input/shape.svg
@@ -0,0 +1,39 @@
+<svg width="7.95in" height="3.70in" version="1.1" viewBox="1956 1041 9354.492 4306.001" xmlns="http://www.w3.org/2000/svg">
+ <polyline transform="translate(-121.88 -68.4)" points="4200 3600 4200 3075 4950 2325 7425 2325 8250 3150 8250 3600" fill="none" stroke="#000" stroke-width="15"/>
+ <polyline transform="translate(-121.88 -68.4)" points="4200 3675 4200 5400" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="8250 3675 8250 5400" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="3675 3600 8700 3600" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="8775 3600 10200 3600" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="8325 3150 9075 3150" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="7500 2325 10200 2325" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="3600 3600 3e3 3600" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="4125 3075 3e3 3075" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="4217 5400 8158 5400" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="8053 5430 8173 5400 8053 5370" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="4322 5370 4202 5400 4322 5430" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="10125 2342 10125 3583" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="10095 3478 10125 3598 10155 3478" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="10155 2447 10125 2327 10095 2447" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="3e3 3167 3e3 3583" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="2970 3478 3e3 3598 3030 3478" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="3030 3272 3e3 3152 2970 3272" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="9075 3167 9075 3583" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="9045 3478 9075 3598 9105 3478" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="9105 3272 9075 3152 9045 3272" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="4950 2325 4950 1200" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="7425 2325 7425 1200" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="4200 3075 4200 2400 3600 1800 3600 1200" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="8250 3150 8250 2475 8775 1950 8775 1200" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="3617 1275 4933 1275" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="4828 1305 4948 1275 4828 1245" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="3722 1245 3602 1275 3722 1305" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="7442 1275 8683 1275" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="8578 1305 8698 1275 8578 1245" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-121.88 -68.4)" points="7547 1245 7427 1275 7547 1305" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <text x="5953.125" y="5256.6001" fill="#000000" font-family="sans-serif" font-size="144px" stroke-width=".025in" text-anchor="middle" xml:space="preserve">Effect duration</text>
+ <text x="10078.125" y="2931.5999" fill="#000000" font-family="sans-serif" font-size="144px" stroke-width=".025in" xml:space="preserve">Effect magnitude</text>
+ <text x="9028.125" y="3381.5999" fill="#000000" font-family="sans-serif" font-size="144px" stroke-width=".025in" xml:space="preserve">Fade level</text>
+ <text x="4153.125" y="1131.6" fill="#000000" font-family="sans-serif" font-size="144px" stroke-width=".025in" text-anchor="middle" xml:space="preserve">Attack length</text>
+ <text x="8053.125" y="1131.6" fill="#000000" font-family="sans-serif" font-size="144px" stroke-width=".025in" text-anchor="middle" xml:space="preserve">Fade length</text>
+ <text x="2803.125" y="3306.5999" fill="#000000" font-family="sans-serif" font-size="144px" stroke-width=".025in" text-anchor="end" xml:space="preserve">Attack level</text>
+</svg>
-- 
2.9.3

[PATCH v2 32/37] docs: input/interactive: convert from xfig to svg

[Mauro Carvalho Chehab]

We're using svg as the standard format for vectorial images.

Convert it to .svg, in a way that it is easily editable.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/interactive.fig | 42 -------------------------------------
 Documentation/input/interactive.svg | 24 +++++++++++++++++++++
 2 files changed, 24 insertions(+), 42 deletions(-)
 delete mode 100644 Documentation/input/interactive.fig
 create mode 100644 Documentation/input/interactive.svg

diff --git a/Documentation/input/interactive.fig b/Documentation/input/interactive.fig
deleted file mode 100644
index 1e7de387723a..000000000000
--- a/Documentation/input/interactive.fig
+++ /dev/null
@@ -1,42 +0,0 @@
-#FIG 3.2
-Landscape
-Center
-Inches
-Letter  
-100.00
-Single
--2
-1200 2
-2 1 0 2 0 7 50 0 -1 6.000 0 0 -1 0 0 6
-	 1200 3600 1800 3600 2400 4800 3000 4800 4200 5700 4800 5700
-2 2 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 5
-	 1200 3150 4800 3150 4800 6300 1200 6300 1200 3150
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 1200 4800 4800 4800
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4
-	 2400 4800 2400 6525 1950 7125 1950 7800
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4
-	 3000 4800 3000 6525 3600 7125 3600 7800
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 1 3
-	0 0 1.00 60.00 120.00
-	 3825 5400 4125 5100 5400 5100
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 1 3
-	0 0 1.00 60.00 120.00
-	 2100 4200 2400 3900 5400 3900
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 4800 5700 5400 5700
-2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2
-	 1800 3600 5400 3600
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 1 3
-	0 0 1.00 60.00 120.00
-	 2700 4800 2700 4425 5400 4425
-2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2
-	0 0 1.00 60.00 120.00
-	0 0 1.00 60.00 120.00
-	 1950 7800 3600 7800
-4 1 0 50 0 0 12 0.0000 4 135 810 2775 7725 Dead band\001
-4 0 0 50 0 0 12 0.0000 4 180 1155 5400 5700 right saturation\001
-4 0 0 50 0 0 12 0.0000 4 135 1065 5400 3600 left saturation\001
-4 0 0 50 0 0 12 0.0000 4 180 2505 5400 3900 left coeff ( positive in that case )\001
-4 0 0 50 0 0 12 0.0000 4 180 2640 5475 5100 right coeff ( negative in that case )\001
-4 0 0 50 0 0 12 0.0000 4 105 480 5400 4425 center\001
diff --git a/Documentation/input/interactive.svg b/Documentation/input/interactive.svg
new file mode 100644
index 000000000000..a3513709a09b
--- /dev/null
+++ b/Documentation/input/interactive.svg
@@ -0,0 +1,24 @@
+<svg width="5.75in" height="3.90in" version="1.1" viewBox="1178 3138 6779.9424 4671.3427" xmlns="http://www.w3.org/2000/svg">
+ <polyline transform="translate(-18.5,-16.294)" points="1200 3600 1800 3600 2400 4800 3e3 4800 4200 5700 4800 5700" fill="none" stroke="#000" stroke-width="15"/>
+ <rect x="1181.5" y="3133.7" width="3600" height="3150" rx="0" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="1200 4800 4800 4800" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="2400 4800 2400 6525 1950 7125 1950 7800" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="3e3 4800 3e3 6525 3600 7125 3600 7800" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="3837 5389 4125 5100 5400 5100" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="3889 5292 3826 5398 3932 5334" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="2112 4189 2400 3900 5400 3900" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="2164 4092 2101 4198 2207 4134" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="4800 5700 5400 5700" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="1800 3600 5400 3600" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="2700 4784 2700 4425 5400 4425" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="2670 4678 2700 4798 2730 4678" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="1967 7800 3583 7800" fill="none" stroke="#000" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="3478 7830 3598 7800 3478 7770" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <polyline transform="translate(-18.5,-16.294)" points="2072 7770 1952 7800 2072 7830" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/>
+ <text x="2775" y="7725" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" text-anchor="middle" xml:space="preserve">Dead band</text>
+ <text x="5400" y="5700" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">right saturation</text>
+ <text x="5400" y="3600" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">left saturation</text>
+ <text x="5400" y="3900" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">left coeff ( positive in that case )</text>
+ <text x="5475" y="5100" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">right coeff ( negative in that case )</text>
+ <text x="5400" y="4425" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">center</text>
+</svg>
-- 
2.9.3

[PATCH v2 33/37] docs: ff.rst: use svg files instead of xfig

[Mauro Carvalho Chehab]

Now that the images got converted to svg, add them at the
ff.rst file.

NOTE: After merging upstream, the "figure" tag should be
replaced by the new "kernel-figure" tag, in order for the
SVG images to be included at the PDF files.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/ff.rst | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/Documentation/input/ff.rst b/Documentation/input/ff.rst
index 6d6688a63dd8..c30f185216a0 100644
--- a/Documentation/input/ff.rst
+++ b/Documentation/input/ff.rst
@@ -5,8 +5,8 @@ Force feedback for Linux
 :Author: Johann Deneux <johann.deneux@gmail.com> on 2001/04/22.
 :Updated: Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09.
 
-You may redistribute this file. Please remember to include shape.fig and
-interactive.fig as well.
+You may redistribute this file. Please remember to include shape.svg and
+interactive.svg as well.
 
 Introduction
 ~~~~~~~~~~~~
@@ -127,8 +127,15 @@ allocate a new effect.
 Effects are file descriptor specific.
 
 See <linux/input.h> for a description of the ff_effect struct. You should also
-find help in a few sketches, contained in files shape.fig and interactive.fig.
-You need xfig to visualize these files.
+find help in a few sketches, contained in files shape.svg and interactive.svg:
+
+.. figure:: shape.svg
+
+    Shape
+
+.. figure:: interactive.svg
+
+    Interactive
 
 
 Removing an effect from the device
-- 
2.9.3

[PATCH v2 34/37] input: add an EV_REL event for high-res vertical wheel

[Mauro Carvalho Chehab]

As some devices can produce either low-res or high-res
vertical wheel EV_REL events, add a new event to allow
userspace to distinguish between them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/event-codes.rst    | 16 +++++++++++++---
 include/uapi/linux/input-event-codes.h |  1 +
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst
index 92db50954169..0c8591d39bc6 100644
--- a/Documentation/input/event-codes.rst
+++ b/Documentation/input/event-codes.rst
@@ -185,10 +185,20 @@ instead of EV_REL codes.
 
 A few EV_REL codes have special meanings:
 
-* REL_WHEEL, REL_HWHEEL:
+* REL_WHEEL:
 
-  - These codes are used for vertical and horizontal scroll wheels,
-    respectively.
+  - These codes are used for vertical scroll wheels.
+
+  - REL_WHEEL is for normal wheel operational mode, e. g. low-resolution
+    (line-based) scroll.
+
+  - REL_HIRES_WHEEL should be used when the wheel has two resolutions and it
+    is in high-resolution mode, e. g. the same angular movement that would
+    produce a single REL_WHEEL will produce multiple REL_HIRES_WHEEL events.
+
+* REL_HWHEEL:
+
+  - This code is used for horizontal scroll wheels.
 
 EV_ABS
 ------
diff --git a/include/uapi/linux/input-event-codes.h b/include/uapi/linux/input-event-codes.h
index 3af60ee69053..23b2d377af59 100644
--- a/include/uapi/linux/input-event-codes.h
+++ b/include/uapi/linux/input-event-codes.h
@@ -703,6 +703,7 @@
 #define REL_DIAL		0x07
 #define REL_WHEEL		0x08
 #define REL_MISC		0x09
+#define REL_HIRES_WHEEL		0x0a
 #define REL_MAX			0x0f
 #define REL_CNT			(REL_MAX+1)
 
-- 
2.9.3

[PATCH v2 35/37] input: add a EV_SW event for ratchet switch

[Mauro Carvalho Chehab]

Some mouses have a switch on their wheel, allowing to switch
between ratchet or free wheel mode. Add support for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/input/event-codes.rst    | 16 ++++++++++++++++
 include/linux/mod_devicetable.h        |  2 +-
 include/uapi/linux/input-event-codes.h |  4 +++-
 3 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst
index 0c8591d39bc6..93f14f0ddb3d 100644
--- a/Documentation/input/event-codes.rst
+++ b/Documentation/input/event-codes.rst
@@ -239,6 +239,22 @@ Upon resume, if the switch state is the same as before suspend, then the input
 subsystem will filter out the duplicate switch state reports. The driver does
 not need to keep the state of the switch at any time.
 
+A few EV_SW codes have special meanings:
+
+* SW_RATCHET:
+
+  - Some mouses have a special switch at their wheel that allows to change
+    from free wheel mode to ratchet mode.
+
+    When such switch is ratchet mode (ON state), the wheel will offer some
+    resistance for movements movement. It will also provide a tactile
+    feedback when scrolled.
+
+    When pressed while in ratchet mode, the wheel will switch to free wheel
+    mode (OFF state). In this mode, it will offer no resistance to wheel
+    movements nor any tactile feedback. Pressing again returns to ratchet
+    mode.
+
 EV_MSC
 ------
 
diff --git a/include/linux/mod_devicetable.h b/include/linux/mod_devicetable.h
index 8850fcaf50db..038cddf1436a 100644
--- a/include/linux/mod_devicetable.h
+++ b/include/linux/mod_devicetable.h
@@ -292,7 +292,7 @@ struct pcmcia_device_id {
 #define INPUT_DEVICE_ID_LED_MAX		0x0f
 #define INPUT_DEVICE_ID_SND_MAX		0x07
 #define INPUT_DEVICE_ID_FF_MAX		0x7f
-#define INPUT_DEVICE_ID_SW_MAX		0x0f
+#define INPUT_DEVICE_ID_SW_MAX		0x1f
 
 #define INPUT_DEVICE_ID_MATCH_BUS	1
 #define INPUT_DEVICE_ID_MATCH_VENDOR	2
diff --git a/include/uapi/linux/input-event-codes.h b/include/uapi/linux/input-event-codes.h
index 23b2d377af59..a3eafd0527f1 100644
--- a/include/uapi/linux/input-event-codes.h
+++ b/include/uapi/linux/input-event-codes.h
@@ -782,7 +782,9 @@
 #define SW_LINEIN_INSERT	0x0d  /* set = inserted */
 #define SW_MUTE_DEVICE		0x0e  /* set = device disabled */
 #define SW_PEN_INSERTED		0x0f  /* set = pen inserted */
-#define SW_MAX			0x0f
+#define SW_RATCHET		0x10  /* set = ratchet mode,
+					 unset: free wheel */
+#define SW_MAX			0x1f
 #define SW_CNT			(SW_MAX+1)
 
 /*
-- 
2.9.3

Re: [PATCH v2 35/37] input: add a EV_SW event for ratchet switch

[Peter Hutterer]

On Tue, Apr 04, 2017 at 09:22:35AM -0300, Mauro Carvalho Chehab wrote:
> Some mouses have a switch on their wheel, allowing to switch

isnt' the plural of mouse mice? (non-native english speaker myself)

> between ratchet or free wheel mode. Add support for it.

s/or/and/

> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/input/event-codes.rst    | 16 ++++++++++++++++
>  include/linux/mod_devicetable.h        |  2 +-
>  include/uapi/linux/input-event-codes.h |  4 +++-
>  3 files changed, 20 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst
> index 0c8591d39bc6..93f14f0ddb3d 100644
> --- a/Documentation/input/event-codes.rst
> +++ b/Documentation/input/event-codes.rst
> @@ -239,6 +239,22 @@ Upon resume, if the switch state is the same as before suspend, then the input
>  subsystem will filter out the duplicate switch state reports. The driver does
>  not need to keep the state of the switch at any time.
>  
> +A few EV_SW codes have special meanings:
> +
> +* SW_RATCHET:
> +
> +  - Some mouses have a special switch at their wheel that allows to change
> +    from free wheel mode to ratchet mode.

"between free wheel mode and ratchet mode"

> +
> +    When such switch is ratchet mode (ON state), the wheel will offer some

s/such/the/

> +    resistance for movements movement. It will also provide a tactile
> +    feedback when scrolled.

this is too specific, you cannot guarantee that all devices in the future
have exactly that behaviour. I would just skip the second sentence.

> +
> +    When pressed while in ratchet mode, the wheel will switch to free wheel
> +    mode (OFF state). In this mode, it will offer no resistance to wheel
> +    movements nor any tactile feedback. Pressing again returns to ratchet
> +    mode.

nack to this, this is your device but not all future devices will have this
behaviour. e.g. some devices have the ratchet switch below (i.e. south of)
the weel. Just describe the effect the switch has, not the physical
behaviour.

Cheers,
   Peter

> +
>  EV_MSC
>  ------
>  
> diff --git a/include/linux/mod_devicetable.h b/include/linux/mod_devicetable.h
> index 8850fcaf50db..038cddf1436a 100644
> --- a/include/linux/mod_devicetable.h
> +++ b/include/linux/mod_devicetable.h
> @@ -292,7 +292,7 @@ struct pcmcia_device_id {
>  #define INPUT_DEVICE_ID_LED_MAX		0x0f
>  #define INPUT_DEVICE_ID_SND_MAX		0x07
>  #define INPUT_DEVICE_ID_FF_MAX		0x7f
> -#define INPUT_DEVICE_ID_SW_MAX		0x0f
> +#define INPUT_DEVICE_ID_SW_MAX		0x1f
>  
>  #define INPUT_DEVICE_ID_MATCH_BUS	1
>  #define INPUT_DEVICE_ID_MATCH_VENDOR	2
> diff --git a/include/uapi/linux/input-event-codes.h b/include/uapi/linux/input-event-codes.h
> index 23b2d377af59..a3eafd0527f1 100644
> --- a/include/uapi/linux/input-event-codes.h
> +++ b/include/uapi/linux/input-event-codes.h
> @@ -782,7 +782,9 @@
>  #define SW_LINEIN_INSERT	0x0d  /* set = inserted */
>  #define SW_MUTE_DEVICE		0x0e  /* set = device disabled */
>  #define SW_PEN_INSERTED		0x0f  /* set = pen inserted */
> -#define SW_MAX			0x0f
> +#define SW_RATCHET		0x10  /* set = ratchet mode,
> +					 unset: free wheel */
> +#define SW_MAX			0x1f
>  #define SW_CNT			(SW_MAX+1)
>  
>  /*
> -- 
> 2.9.3
> 

Re: [PATCH v2 35/37] input: add a EV_SW event for ratchet switch

[Mauro Carvalho Chehab]

Em Wed, 5 Apr 2017 22:03:03 +1000
Peter Hutterer <peter.hutterer@who-t.net> escreveu:

> On Tue, Apr 04, 2017 at 09:22:35AM -0300, Mauro Carvalho Chehab wrote:
> > Some mouses have a switch on their wheel, allowing to switch  
> 
> isnt' the plural of mouse mice? (non-native english speaker myself)

Yeah, true. I'll fix on a next review.
> 
> > between ratchet or free wheel mode. Add support for it.  
> 
> s/or/and/
> 
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> >  Documentation/input/event-codes.rst    | 16 ++++++++++++++++
> >  include/linux/mod_devicetable.h        |  2 +-
> >  include/uapi/linux/input-event-codes.h |  4 +++-
> >  3 files changed, 20 insertions(+), 2 deletions(-)
> > 
> > diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst
> > index 0c8591d39bc6..93f14f0ddb3d 100644
> > --- a/Documentation/input/event-codes.rst
> > +++ b/Documentation/input/event-codes.rst
> > @@ -239,6 +239,22 @@ Upon resume, if the switch state is the same as before suspend, then the input
> >  subsystem will filter out the duplicate switch state reports. The driver does
> >  not need to keep the state of the switch at any time.
> >  
> > +A few EV_SW codes have special meanings:
> > +
> > +* SW_RATCHET:
> > +
> > +  - Some mouses have a special switch at their wheel that allows to change
> > +    from free wheel mode to ratchet mode.  
> 
> "between free wheel mode and ratchet mode"
> 
> > +
> > +    When such switch is ratchet mode (ON state), the wheel will offer some  
> 
> s/such/the/
> 
> > +    resistance for movements movement. It will also provide a tactile
> > +    feedback when scrolled.  
> 
> this is too specific, you cannot guarantee that all devices in the future
> have exactly that behaviour. I would just skip the second sentence.

I just wanted to let it clear about what's the difference between ratchet
and free wheel mode. As a non-native speaker, I had to research myself
about what the heck "ratchet" means, as I never heard this word before ;)

To be frank, when I received this mouse, I had some troubles to adapt
to it, as on other mice I have here, the wheel is used generate the
mid button event. On this specific model, there's a small button on
south of the wheel the mid button event.

> > +
> > +    When pressed while in ratchet mode, the wheel will switch to free wheel
> > +    mode (OFF state). In this mode, it will offer no resistance to wheel
> > +    movements nor any tactile feedback. Pressing again returns to ratchet
> > +    mode.  
> 
> nack to this, this is your device but not all future devices will have this
> behaviour. e.g. some devices have the ratchet switch below (i.e. south of)
> the weel. Just describe the effect the switch has, not the physical
> behaviour.

Ok, I'll remove it. What about this:

* SW_RATCHET:

  - Some mice have a special switch at their wheel that allows to change
    between free wheel mode and ratchet mode via a ratchet switch.

    When the switch is ratchet mode (ON state), the wheel will offer some
    resistance for movements. It may also provide a tactile feedback when 
    scrolled.

Regards,
Mauro

Re: [PATCH v2 35/37] input: add a EV_SW event for ratchet switch

[Peter Hutterer]

On Thu, Apr 06, 2017 at 09:16:05PM -0300, Mauro Carvalho Chehab wrote:
> Em Wed, 5 Apr 2017 22:03:03 +1000
> Peter Hutterer <peter.hutterer@who-t.net> escreveu:
> 
> > On Tue, Apr 04, 2017 at 09:22:35AM -0300, Mauro Carvalho Chehab wrote:
> > > Some mouses have a switch on their wheel, allowing to switch  
> > 
> > isnt' the plural of mouse mice? (non-native english speaker myself)
> 
> Yeah, true. I'll fix on a next review.
> > 
> > > between ratchet or free wheel mode. Add support for it.  
> > 
> > s/or/and/
> > 
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > > ---
> > >  Documentation/input/event-codes.rst    | 16 ++++++++++++++++
> > >  include/linux/mod_devicetable.h        |  2 +-
> > >  include/uapi/linux/input-event-codes.h |  4 +++-
> > >  3 files changed, 20 insertions(+), 2 deletions(-)
> > > 
> > > diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst
> > > index 0c8591d39bc6..93f14f0ddb3d 100644
> > > --- a/Documentation/input/event-codes.rst
> > > +++ b/Documentation/input/event-codes.rst
> > > @@ -239,6 +239,22 @@ Upon resume, if the switch state is the same as before suspend, then the input
> > >  subsystem will filter out the duplicate switch state reports. The driver does
> > >  not need to keep the state of the switch at any time.
> > >  
> > > +A few EV_SW codes have special meanings:
> > > +
> > > +* SW_RATCHET:
> > > +
> > > +  - Some mouses have a special switch at their wheel that allows to change
> > > +    from free wheel mode to ratchet mode.  
> > 
> > "between free wheel mode and ratchet mode"
> > 
> > > +
> > > +    When such switch is ratchet mode (ON state), the wheel will offer some  
> > 
> > s/such/the/
> > 
> > > +    resistance for movements movement. It will also provide a tactile
> > > +    feedback when scrolled.  
> > 
> > this is too specific, you cannot guarantee that all devices in the future
> > have exactly that behaviour. I would just skip the second sentence.
> 
> I just wanted to let it clear about what's the difference between ratchet
> and free wheel mode. As a non-native speaker, I had to research myself
> about what the heck "ratchet" means, as I never heard this word before ;)
> 
> To be frank, when I received this mouse, I had some troubles to adapt
> to it, as on other mice I have here, the wheel is used generate the
> mid button event. On this specific model, there's a small button on
> south of the wheel the mid button event.
> 
> > > +
> > > +    When pressed while in ratchet mode, the wheel will switch to free wheel
> > > +    mode (OFF state). In this mode, it will offer no resistance to wheel
> > > +    movements nor any tactile feedback. Pressing again returns to ratchet
> > > +    mode.  
> > 
> > nack to this, this is your device but not all future devices will have this
> > behaviour. e.g. some devices have the ratchet switch below (i.e. south of)
> > the weel. Just describe the effect the switch has, not the physical
> > behaviour.
> 
> Ok, I'll remove it. What about this:
> 
> * SW_RATCHET:
> 
>   - Some mice have a special switch at their wheel that allows to change
>     between free wheel mode and ratchet mode via a ratchet switch.
> 
>     When the switch is ratchet mode (ON state), the wheel will offer some
>     resistance for movements. It may also provide a tactile feedback when 
>     scrolled.
 
yep, close, just a minor nitpick:

   - Some mice have a special switch for their wheel that allows to change
     between free wheel mode and ratchet mode. When the switch is ratchet
     mode (ON state), the wheel will offer some resistance for movements. It
     may also provide a tactile feedback when scrolled.


And maybe add something like:
     Note that some mice have a ratchet switch that does not generate a
     software event.

Cheers,
  Peter

[PATCH v2 36/37] hid-logitech-hidpp: add support for high res wheel

[Mauro Carvalho Chehab]

Some Logitech mouses (MX Anyware 2 and MX Master) have support
for a high-resolution wheel.

This wheel can work in backward-compatible mode, generating
wheel events via HID normal events, or it can use new
HID++ events that report not only the wheel movement, but also
the resolution.

Add support for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 drivers/hid/hid-logitech-hidpp.c | 199 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 199 insertions(+)

diff --git a/drivers/hid/hid-logitech-hidpp.c b/drivers/hid/hid-logitech-hidpp.c
index 2e2515a4c070..c208a5107511 100644
--- a/drivers/hid/hid-logitech-hidpp.c
+++ b/drivers/hid/hid-logitech-hidpp.c
@@ -62,6 +62,7 @@ MODULE_PARM_DESC(disable_tap_to_click,
 #define HIDPP_QUIRK_WTP_PHYSICAL_BUTTONS	BIT(22)
 #define HIDPP_QUIRK_NO_HIDINPUT			BIT(23)
 #define HIDPP_QUIRK_FORCE_OUTPUT_REPORTS	BIT(24)
+#define HIDPP_QUIRK_HIRES_SCROLL		BIT(25)
 
 #define HIDPP_QUIRK_DELAYED_INIT		(HIDPP_QUIRK_NO_HIDINPUT | \
 						 HIDPP_QUIRK_CONNECT_EVENTS)
@@ -1361,6 +1362,67 @@ static int hidpp_ff_deinit(struct hid_device *hid)
 	return 0;
 }
 
+/* -------------------------------------------------------------------------- */
+/* 0x2121: High Resolution Wheel                                              */
+/* -------------------------------------------------------------------------- */
+
+#define HIDPP_HIGH_RES_WHEEL		0x2121
+
+#define CMD_MOUSE_SET_WHEEL_MODE	0x20
+#define CMD_MOUSE_GET_WHEEL_RATCHET	0x30
+
+struct high_res_wheel_data {
+	u8 feature_index;
+	struct input_dev *input;
+	bool ratchet;
+};
+
+/**
+ * hidpp_mouse_set_wheel_mode - Sets high resolution wheel mode
+ *
+ * @invert:	if true, inverts wheel movement
+ * @high_res:	if true, wheel is in high-resolution mode. Otherwise, low res
+ * @hidpp:	if true, report wheel events via HID++ notification. If false,
+ *		use standard HID events
+ */
+static int hidpp_mouse_set_wheel_mode(struct hidpp_device *hidpp,
+				      bool invert,
+				      bool high_res,
+				      bool hidpp_mode)
+{
+	struct high_res_wheel_data *hrd = hidpp->private_data;
+	u8 feature_type;
+	struct hidpp_report response;
+	int ret;
+	u8 params[16] = { 0 };
+
+	if (!hrd->feature_index) {
+		ret = hidpp_root_get_feature(hidpp,
+					    HIDPP_HIGH_RES_WHEEL,
+					    &hrd->feature_index,
+					    &feature_type);
+		if (ret)
+			/* means that the device is not powered up */
+			return ret;
+	}
+
+	params[0] = invert     ? 0x4 : 0  |
+		    high_res   ? 0x2 : 0  |
+		    hidpp_mode ? 0x1 : 0;
+
+	ret = hidpp_send_fap_command_sync(hidpp, hrd->feature_index,
+					  CMD_MOUSE_SET_WHEEL_MODE,
+					  params, 16, &response);
+	if (ret > 0) {
+		hid_err(hidpp->hid_dev, "%s: received protocol error 0x%02x\n",
+			__func__, ret);
+		return -EPROTO;
+	}
+	if (ret)
+		return ret;
+
+	return 0;
+}
 
 /* ************************************************************************** */
 /*                                                                            */
@@ -1816,6 +1878,119 @@ static int m560_input_mapping(struct hid_device *hdev, struct hid_input *hi,
 }
 
 /* ------------------------------------------------------------------------- */
+/* Logitech mouse devices with high resolution wheel                         */
+/* ------------------------------------------------------------------------- */
+
+static int high_res_raw_event(struct hid_device *hdev, u8 *data, int size)
+{
+	struct hidpp_device *hidpp = hid_get_drvdata(hdev);
+	struct high_res_wheel_data *hrd = hidpp->private_data;
+
+	/* Don't handle special raw events before setting feature_index */
+	if (!hrd || !hrd->feature_index)
+		return 0;
+
+	if (data[0] != REPORT_ID_HIDPP_LONG ||
+	    data[2] != hrd->feature_index)
+		return 1;
+
+	if (size < 8) {
+		hid_err(hdev, "error in report: size = %d: %*ph\n", size,
+			size, data);
+		return 0;
+	}
+
+	/*
+	 * high res wheel mouse events
+	 *
+	 * Wheel movement events are like:
+	 *
+	 * 11 03 0b 00 01 00 01 00 00 00 00 00 00 00 00 00 00 00 00 00
+	 *
+	 * data[0] = 0x11
+	 * data[1] = device-id
+	 * data[2] = feature index (0b)
+	 * data[3] = event type: 0x00 - wheel movement
+	 * data[4] = bitmask:
+	 *		bits 0-3: number of sampling periods combined
+	 *		bit 4:
+	 *			0 = low resolution
+	 *			1 = high resolution
+	 * data[5] - deltaV MSB
+	 * data[6] = deltaV LSB
+	 * Remaining payload is reserved
+	 *
+	 * Ratchet events are like:
+	 * 11 03 0b 10 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+	 *
+	 * data[0] = 0x11
+	 * data[1] = device-id
+	 * data[2] = feature index
+	 * data[3] = event type: 0x10 - ratchet state
+	 * data[4] = bit 0:
+	 *		1 = ratchet
+	 *		0 = free wheel
+	 * Remaining payload is reserved
+	 */
+
+	if (data[3] == 0) {
+		s16 delta = data[6] | data[5] << 8;
+		bool res = data[4] & 0x10;
+
+		/*
+		 * Report high-resolution events as REL_HWHEEL and
+		 * low-resolution events as REL_WHEEL.
+		 */
+		if (res)
+			input_report_rel(hrd->input, REL_HIRES_WHEEL, delta);
+		else
+			input_report_rel(hrd->input, REL_WHEEL, delta);
+	}
+
+	/* FIXME: also report ratchet events to userspace */
+
+	return 1;
+}
+
+static void high_res_populate_input(struct hidpp_device *hidpp,
+		struct input_dev *input_dev, bool origin_is_hid_core)
+{
+	struct high_res_wheel_data *hrd = hidpp->private_data;
+
+	hrd->input = input_dev;
+
+	__set_bit(REL_WHEEL, hrd->input->relbit);
+	__set_bit(REL_HIRES_WHEEL, hrd->input->relbit);
+}
+
+
+static int high_res_allocate(struct hid_device *hdev)
+{
+	struct hidpp_device *hidpp = hid_get_drvdata(hdev);
+	struct high_res_wheel_data *hrd;
+
+	hrd = devm_kzalloc(&hdev->dev, sizeof(struct high_res_wheel_data),
+			GFP_KERNEL);
+	if (!hrd)
+		return -ENOMEM;
+
+	hidpp->private_data = hrd;
+
+	return 0;
+};
+
+static int high_res_connect(struct hid_device *hdev, bool connected)
+{
+	struct hidpp_device *hidpp = hid_get_drvdata(hdev);
+
+	if (!connected)
+		return 0;
+
+	/* Enable HID++ wheel event output mode */
+	return hidpp_mouse_set_wheel_mode(hidpp, false, false, true);
+}
+
+/* ------------------------------------------------------------------------- */
 /* Logitech K400 devices                                                     */
 /* ------------------------------------------------------------------------- */
 
@@ -1955,6 +2130,9 @@ static void hidpp_populate_input(struct hidpp_device *hidpp,
 		wtp_populate_input(hidpp, input, origin_is_hid_core);
 	else if (hidpp->quirks & HIDPP_QUIRK_CLASS_M560)
 		m560_populate_input(hidpp, input, origin_is_hid_core);
+	else if (hidpp->quirks & HIDPP_QUIRK_HIRES_SCROLL)
+		high_res_populate_input(hidpp, input, origin_is_hid_core);
+
 }
 
 static int hidpp_input_configured(struct hid_device *hdev,
@@ -2054,6 +2232,8 @@ static int hidpp_raw_event(struct hid_device *hdev, struct hid_report *report,
 		return wtp_raw_event(hdev, data, size);
 	else if (hidpp->quirks & HIDPP_QUIRK_CLASS_M560)
 		return m560_raw_event(hdev, data, size);
+	else if (hidpp->quirks & HIDPP_QUIRK_HIRES_SCROLL)
+		return high_res_raw_event(hdev, data, size);
 
 	return 0;
 }
@@ -2141,6 +2321,10 @@ static void hidpp_connect_event(struct hidpp_device *hidpp)
 		ret = k400_connect(hdev, connected);
 		if (ret)
 			return;
+	} else if (hidpp->quirks & HIDPP_QUIRK_HIRES_SCROLL) {
+		ret = high_res_connect(hdev, connected);
+		if (ret)
+			return;
 	}
 
 	if (!connected || hidpp->delayed_input)
@@ -2215,6 +2399,7 @@ static int hidpp_probe(struct hid_device *hdev, const struct hid_device_id *id)
 		hidpp->quirks &= ~HIDPP_QUIRK_CLASS_WTP;
 		hidpp->quirks &= ~HIDPP_QUIRK_CONNECT_EVENTS;
 		hidpp->quirks &= ~HIDPP_QUIRK_NO_HIDINPUT;
+		hidpp->quirks &= ~HIDPP_QUIRK_HIRES_SCROLL;
 	}
 
 	if (hidpp->quirks & HIDPP_QUIRK_CLASS_WTP) {
@@ -2229,6 +2414,10 @@ static int hidpp_probe(struct hid_device *hdev, const struct hid_device_id *id)
 		ret = k400_allocate(hdev);
 		if (ret)
 			goto allocate_fail;
+	} else if (hidpp->quirks & HIDPP_QUIRK_HIRES_SCROLL) {
+		ret = high_res_allocate(hdev);
+		if (ret)
+			goto allocate_fail;
 	}
 
 	INIT_WORK(&hidpp->work, delayed_work_cb);
@@ -2354,6 +2543,16 @@ static const struct hid_device_id hidpp_devices[] = {
 	  HID_DEVICE(BUS_USB, HID_GROUP_LOGITECH_DJ_DEVICE,
 		USB_VENDOR_ID_LOGITECH, 0x402d),
 	  .driver_data = HIDPP_QUIRK_DELAYED_INIT | HIDPP_QUIRK_CLASS_M560 },
+	{ /* Logitech MX Master with high resolution scroll */
+	  HID_DEVICE(BUS_USB, HID_GROUP_LOGITECH_DJ_DEVICE,
+		USB_VENDOR_ID_LOGITECH, 0x4041),
+	  .driver_data = HIDPP_QUIRK_CONNECT_EVENTS |
+			 HIDPP_QUIRK_HIRES_SCROLL },
+	{ /* Logitech MX Anywhere 2 with high resolution scroll */
+	  HID_DEVICE(BUS_USB, HID_GROUP_LOGITECH_DJ_DEVICE,
+		USB_VENDOR_ID_LOGITECH, 0x404a),
+	  .driver_data = HIDPP_QUIRK_CONNECT_EVENTS |
+			 HIDPP_QUIRK_HIRES_SCROLL },
 	{ /* Keyboard logitech K400 */
 	  HID_DEVICE(BUS_USB, HID_GROUP_LOGITECH_DJ_DEVICE,
 		USB_VENDOR_ID_LOGITECH, 0x4024),
-- 
2.9.3

[PATCH v2 37/37] hid-logitech-hidpp: add support for ratchet switch

[Mauro Carvalho Chehab]

Logitech Anywhere MX2 and MX master produce events for
the wheel ratchet/free wheel button. Add support for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 drivers/hid/hid-logitech-hidpp.c | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/drivers/hid/hid-logitech-hidpp.c b/drivers/hid/hid-logitech-hidpp.c
index c208a5107511..6177087ffaca 100644
--- a/drivers/hid/hid-logitech-hidpp.c
+++ b/drivers/hid/hid-logitech-hidpp.c
@@ -1406,6 +1406,19 @@ static int hidpp_mouse_set_wheel_mode(struct hidpp_device *hidpp,
 			return ret;
 	}
 
+	ret = hidpp_send_fap_command_sync(hidpp, hrd->feature_index,
+					  CMD_MOUSE_GET_WHEEL_RATCHET,
+					  params, 16, &response);
+	if (ret > 0) {
+		hid_err(hidpp->hid_dev, "%s: received protocol error 0x%02x\n",
+			__func__, ret);
+		return -EPROTO;
+	}
+	if (ret)
+		return ret;
+
+	hrd->ratchet = response.fap.params[0] & 0x01;
+
 	params[0] = invert     ? 0x4 : 0  |
 		    high_res   ? 0x2 : 0  |
 		    hidpp_mode ? 0x1 : 0;
@@ -1945,10 +1958,11 @@ static int high_res_raw_event(struct hid_device *hdev, u8 *data, int size)
 			input_report_rel(hrd->input, REL_HIRES_WHEEL, delta);
 		else
 			input_report_rel(hrd->input, REL_WHEEL, delta);
+	} else if (data[3] == 0x10) {
+		hrd->ratchet = data[4] & 0x01;
+		input_report_switch(hrd->input, SW_RATCHET, hrd->ratchet);
 	}
 
-	/* FIXME: also report ratchet events to userspace */
-
 	return 1;
 }
 
@@ -1961,6 +1975,11 @@ static void high_res_populate_input(struct hidpp_device *hidpp,
 
 	__set_bit(REL_WHEEL, hrd->input->relbit);
 	__set_bit(REL_HIRES_WHEEL, hrd->input->relbit);
+	__set_bit(EV_SW, hrd->input->evbit);
+	__set_bit(SW_RATCHET, hrd->input->swbit);
+
+	/* Report current state of the ratchet switch */
+	input_report_switch(hrd->input, SW_RATCHET, hrd->ratchet);
 }
 
 
-- 
2.9.3