~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/input/gamepad.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

  1 ---------------------------
  2 Linux Gamepad Specification
  3 ---------------------------
  4 
  5 :Author: 2013 by David Herrmann <dh.herrmann@gmail.com>
  6 
  7 
  8 Introduction
  9 ~~~~~~~~~~~~
 10 Linux provides many different input drivers for gamepad hardware. To avoid
 11 having user-space deal with different button-mappings for each gamepad, this
 12 document defines how gamepads are supposed to report their data.
 13 
 14 Geometry
 15 ~~~~~~~~
 16 As "gamepad" we define devices which roughly look like this::
 17 
 18             ____________________________              __
 19            / [__ZL__]          [__ZR__] \               |
 20           / [__ TL __]        [__ TR __] \              | Front Triggers
 21        __/________________________________\__         __|
 22       /                                  _   \          |
 23      /      /\           __             (N)   \         |
 24     /       ||      __  |MO|  __     _       _ \        | Main Pad
 25    |    <===DP===> |SE|      |ST|   (W) -|- (E) |       |
 26     \       ||    ___          ___       _     /        |
 27     /\      \/   /   \        /   \     (S)   /\      __|
 28    /  \________ | LS  | ____ |  RS | ________/  \       |
 29   |         /  \ \___/ /    \ \___/ /  \         |      | Control Sticks
 30   |        /    \_____/      \_____/    \        |    __|
 31   |       /                              \       |
 32    \_____/                                \_____/
 33 
 34        |________|______|    |______|___________|
 35          D-Pad    Left       Right   Action Pad
 36                  Stick       Stick
 37 
 38                    |_____________|
 39                       Menu Pad
 40 
 41 Most gamepads have the following features:
 42 
 43   - Action-Pad
 44     4 buttons in diamonds-shape (on the right side). The buttons are
 45     differently labeled on most devices so we define them as NORTH,
 46     SOUTH, WEST and EAST.
 47   - D-Pad (Direction-pad)
 48     4 buttons (on the left side) that point up, down, left and right.
 49   - Menu-Pad
 50     Different constellations, but most-times 2 buttons: SELECT - START
 51     Furthermore, many gamepads have a fancy branded button that is used as
 52     special system-button. It often looks different to the other buttons and
 53     is used to pop up system-menus or system-settings.
 54   - Analog-Sticks
 55     Analog-sticks provide freely moveable sticks to control directions. Not
 56     all devices have both or any, but they are present at most times.
 57     Analog-sticks may also provide a digital button if you press them.
 58   - Triggers
 59     Triggers are located on the upper-side of the pad in vertical direction.
 60     Not all devices provide them, but the upper buttons are normally named
 61     Left- and Right-Triggers, the lower buttons Z-Left and Z-Right.
 62   - Rumble
 63     Many devices provide force-feedback features. But are mostly just
 64     simple rumble motors.
 65 
 66 Detection
 67 ~~~~~~~~~
 68 
 69 All gamepads that follow the protocol described here map BTN_GAMEPAD. This is
 70 an alias for BTN_SOUTH/BTN_A. It can be used to identify a gamepad as such.
 71 However, not all gamepads provide all features, so you need to test for all
 72 features that you need, first. How each feature is mapped is described below.
 73 
 74 Legacy drivers often don't comply to these rules. As we cannot change them
 75 for backwards-compatibility reasons, you need to provide fixup mappings in
 76 user-space yourself. Some of them might also provide module-options that
 77 change the mappings so you can advise users to set these.
 78 
 79 All new gamepads are supposed to comply with this mapping. Please report any
 80 bugs, if they don't.
 81 
 82 There are a lot of less-featured/less-powerful devices out there, which re-use
 83 the buttons from this protocol. However, they try to do this in a compatible
 84 fashion. For example, the "Nintendo Wii Nunchuk" provides two trigger buttons
 85 and one analog stick. It reports them as if it were a gamepad with only one
 86 analog stick and two trigger buttons on the right side.
 87 But that means, that if you only support "real" gamepads, you must test
 88 devices for _all_ reported events that you need. Otherwise, you will also get
 89 devices that report a small subset of the events.
 90 
 91 No other devices, that do not look/feel like a gamepad, shall report these
 92 events.
 93 
 94 Events
 95 ~~~~~~
 96 
 97 Gamepads report the following events:
 98 
 99 - Action-Pad:
100 
101   Every gamepad device has at least 2 action buttons. This means, that every
102   device reports BTN_SOUTH (which BTN_GAMEPAD is an alias for). Regardless
103   of the labels on the buttons, the codes are sent according to the
104   physical position of the buttons.
105 
106   Please note that 2- and 3-button pads are fairly rare and old. You might
107   want to filter gamepads that do not report all four.
108 
109     - 2-Button Pad:
110 
111       If only 2 action-buttons are present, they are reported as BTN_SOUTH and
112       BTN_EAST. For vertical layouts, the upper button is BTN_EAST. For
113       horizontal layouts, the button more on the right is BTN_EAST.
114 
115     - 3-Button Pad:
116 
117       If only 3 action-buttons are present, they are reported as (from left
118       to right): BTN_WEST, BTN_SOUTH, BTN_EAST
119       If the buttons are aligned perfectly vertically, they are reported as
120       (from top down): BTN_WEST, BTN_SOUTH, BTN_EAST
121 
122     - 4-Button Pad:
123 
124       If all 4 action-buttons are present, they can be aligned in two
125       different formations. If diamond-shaped, they are reported as BTN_NORTH,
126       BTN_WEST, BTN_SOUTH, BTN_EAST according to their physical location.
127       If rectangular-shaped, the upper-left button is BTN_NORTH, lower-left
128       is BTN_WEST, lower-right is BTN_SOUTH and upper-right is BTN_EAST.
129 
130 - D-Pad:
131 
132   Every gamepad provides a D-Pad with four directions: Up, Down, Left, Right
133   Some of these are available as digital buttons, some as analog buttons. Some
134   may even report both. The kernel does not convert between these so
135   applications should support both and choose what is more appropriate if
136   both are reported.
137 
138     - Digital buttons are reported as:
139 
140       BTN_DPAD_*
141 
142     - Analog buttons are reported as:
143 
144       ABS_HAT0X and ABS_HAT0Y
145 
146   (for ABS values negative is left/up, positive is right/down)
147 
148 - Analog-Sticks:
149 
150   The left analog-stick is reported as ABS_X, ABS_Y. The right analog stick is
151   reported as ABS_RX, ABS_RY. Zero, one or two sticks may be present.
152   If analog-sticks provide digital buttons, they are mapped accordingly as
153   BTN_THUMBL (first/left) and BTN_THUMBR (second/right).
154 
155   (for ABS values negative is left/up, positive is right/down)
156 
157 - Triggers:
158 
159   Trigger buttons can be available as digital or analog buttons or both. User-
160   space must correctly deal with any situation and choose the most appropriate
161   mode.
162 
163   Upper trigger buttons are reported as BTN_TR or ABS_HAT1X (right) and BTN_TL
164   or ABS_HAT1Y (left). Lower trigger buttons are reported as BTN_TR2 or
165   ABS_HAT2X (right/ZR) and BTN_TL2 or ABS_HAT2Y (left/ZL).
166 
167   If only one trigger-button combination is present (upper+lower), they are
168   reported as "right" triggers (BTN_TR/ABS_HAT1X).
169 
170   (ABS trigger values start at 0, pressure is reported as positive values)
171 
172 - Menu-Pad:
173 
174   Menu buttons are always digital and are mapped according to their location
175   instead of their labels. That is:
176 
177     - 1-button Pad:
178 
179       Mapped as BTN_START
180 
181     - 2-button Pad:
182 
183       Left button mapped as BTN_SELECT, right button mapped as BTN_START
184 
185   Many pads also have a third button which is branded or has a special symbol
186   and meaning. Such buttons are mapped as BTN_MODE. Examples are the Nintendo
187   "HOME" button, the Xbox "X" button or the Sony PlayStation "PS" button.
188 
189 - Rumble:
190 
191   Rumble is advertised as FF_RUMBLE.
192 
193 - Profile:
194 
195   Some pads provide a multi-value profile selection switch.  An example is the
196   XBox Adaptive and the XBox Elite 2 controllers.  When the active profile is
197   switched, its newly selected value is emitted as an ABS_PROFILE event.

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php