From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: linux-input@vger.kernel.org, Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>,
Linux Doc Mailing List <linux-doc@vger.kernel.org>,
Jonathan Corbet <corbet@lwn.net>
Subject: [PATCH v2 13/37] docs: input/gamepad: convert it to ReST format
Date: Tue, 4 Apr 2017 09:22:13 -0300 [thread overview]
Message-ID: <3efc02b3379dc908bfc0ade34185469295fee2bc.1491308444.git.mchehab@s-opensource.com> (raw)
In-Reply-To: <95dd0d035385dac833029e1db56846f02b3ae69c.1491308444.git.mchehab@s-opensource.com>
In-Reply-To: <67ed7b07043e6fac94528044ebaf541d5deb7c82.1491308444.git.mchehab@s-opensource.com>
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
next prev parent reply other threads:[~2017-04-04 12:23 UTC|newest]
Thread overview: 55+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-04-04 10:52 [PATCH v2 00/33] Convert input documentation to ReST Mauro Carvalho Chehab
2017-04-04 10:52 ` [PATCH v2 01/33] docs: Documentation/input/input: convert it to ReST format Mauro Carvalho Chehab
[not found] ` <8e64d13bfc6952bc9370593ddc556a539f589654.1491302719.git.mchehab@s-opensource.com>
[not found] ` <781a89b410f25a2fb39d081d1ebd696317b6d2c2.1491302719.git.mchehab@s-opensource.com>
[not found] ` <6800b2c4e8f67b699c22533f7574d380b37cb6d6.1491302719.git.mchehab@s-opensource.com>
[not found] ` <9f6ae6ca543f4aa294afd000b7c8a8f49b2e8382.1491302719.git.mchehab@s-opensource.com>
2017-04-04 10:52 ` [PATCH v2 06/33] docs: input/bcm5974: " Mauro Carvalho Chehab
2017-04-04 10:52 ` [PATCH v2 07/33] docs: input/cd32: " Mauro Carvalho Chehab
[not found] ` <e67db9bffc4a93a93b8559ed85d6e77045a99157.1491302719.git.mchehab@s-opensource.com>
[not found] ` <9794ec8a2147f66e9e183f612fa7e834c9245dd9.1491302719.git.mchehab@s-opensource.com>
[not found] ` <3bb792c867ec11d1e5b998b2d44e99fbd654ff95.1491302719.git.mchehab@s-opensource.com>
2017-04-04 10:52 ` [PATCH v2 11/33] docs: input/event-codes: " Mauro Carvalho Chehab
2017-04-04 10:52 ` [PATCH v2 12/33] docs: input/ff: " Mauro Carvalho Chehab
[not found] ` <3efc02b3379dc908bfc0ade34185469295fee2bc.1491302719.git.mchehab@s-opensource.com>
[not found] ` <9b1b818d7cde485713aced6b077f0e276a24bddd.1491302719.git.mchehab@s-opensource.com>
2017-04-04 10:52 ` [PATCH v2 15/33] docs: input/gpio-tilt: " Mauro Carvalho Chehab
[not found] ` <8e0ef882aa235e4e6e758662dc434567266fb541.1491302719.git.mchehab@s-opensource.com>
2017-04-04 10:52 ` [PATCH v2 17/33] docs: input/input-programming: " Mauro Carvalho Chehab
[not found] ` <c4d96be24099f525b771369e2c0dd9bdfd376fa0.1491302719.git.mchehab@s-opensource.com>
2017-04-04 10:52 ` [PATCH v2 19/33] docs: input/joystick: " Mauro Carvalho Chehab
2017-04-04 10:52 ` [PATCH v2 20/33] docs: input/joystick-parport: " Mauro Carvalho Chehab
[not found] ` <e297fc785d72be336c2e4a85705c24eedb16cf7d.1491302719.git.mchehab@s-opensource.com>
2017-04-04 10:52 ` [PATCH v2 22/33] docs: input/notifier: " Mauro Carvalho Chehab
[not found] ` <c6f7140e3bdbfb30a338550b700d25667b764594.1491302719.git.mchehab@s-opensource.com>
[not found] ` <3552e3986d3848001b89449926d04f44930c681e.1491302719.git.mchehab@s-opensource.com>
2017-04-04 10:52 ` [PATCH v2 25/33] docs: input/sentelic: " Mauro Carvalho Chehab
[not found] ` <679c283194489e852074900b0133b5b6acd9395f.1491302719.git.mchehab@s-opensource.com>
2017-04-04 10:52 ` [PATCH v2 27/33] docs: input/walkera0701: " Mauro Carvalho Chehab
[not found] ` <ff44ad91600b12a8475e3e46a8a121dcbd3eedd9.1491302719.git.mchehab@s-opensource.com>
[not found] ` <55d263f13237495276213de295ae1c6d67f0588b.1491302719.git.mchehab@s-opensource.com>
2017-04-04 10:52 ` [PATCH v2 30/33] docs-rst: create a book with Linux Input documentation Mauro Carvalho Chehab
[not found] ` <a6e09069e3a232652651c2aac6d0906e728422e2.1491302719.git.mchehab@s-opensource.com>
2017-04-04 10:52 ` [PATCH v2 32/33] docs: input/interactive: convert from xfig to svg Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 01/37] docs: Documentation/input/input: convert it to ReST format Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 02/37] docs: input/alps: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 03/37] docs: input/amijoy: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 04/37] docs: input/appletouch: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 05/37] docs: input/atarikbd: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 06/37] docs: input/bcm5974: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 07/37] docs: input/cd32: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 08/37] docs: input/cma3000_d0x: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 09/37] docs: input/cs461x: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 10/37] docs: input/elantech: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 11/37] docs: input/event-codes: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 12/37] docs: input/ff: " Mauro Carvalho Chehab
2017-04-04 12:22 ` Mauro Carvalho Chehab [this message]
2017-04-04 12:22 ` [PATCH v2 14/37] docs: input/gameport-programming: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 15/37] docs: input/gpio-tilt: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 16/37] docs: input/iforce-protocol: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 17/37] docs: input/input-programming: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 18/37] docs: input/joystick-api: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 19/37] docs: input/joystick: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 20/37] docs: input/joystick-parport: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 21/37] docs: input/multi-touch-protocol: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 22/37] docs: input/notifier: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 23/37] docs: input/ntrig: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 24/37] docs: input/rotary-encoder: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 25/37] docs: input/sentelic: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 26/37] docs: input/userio: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 27/37] docs: input/walkera0701: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 28/37] docs: input/xpad: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 29/37] docs: input/yealink: " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 30/37] docs-rst: create a book with Linux Input documentation Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 31/37] docs: input/shape: convert it from xfig to svg Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 32/37] docs: input/interactive: convert " Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 33/37] docs: ff.rst: use svg files instead of xfig Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 34/37] input: add an EV_REL event for high-res vertical wheel Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 35/37] input: add a EV_SW event for ratchet switch Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 36/37] hid-logitech-hidpp: add support for high res wheel Mauro Carvalho Chehab
2017-04-04 12:22 ` [PATCH v2 37/37] hid-logitech-hidpp: add support for ratchet switch Mauro Carvalho Chehab
2017-04-05 12:03 ` [PATCH v2 35/37] input: add a EV_SW event " Peter Hutterer
2017-04-07 0:16 ` Mauro Carvalho Chehab
2017-04-07 0:53 ` Peter Hutterer
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=3efc02b3379dc908bfc0ade34185469295fee2bc.1491308444.git.mchehab@s-opensource.com \
--to=mchehab@s-opensource.com \
--cc=corbet@lwn.net \
--cc=dmitry.torokhov@gmail.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-input@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.