Documentation/input/gamepad.rst

Source file repositories/reference/linux-study-clean/Documentation/input/gamepad.rst

File Facts

System
Linux kernel
Corpus path
Documentation/input/gamepad.rst
Extension
.rst
Size
8417 bytes
Lines
211
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

---------------------------
Linux Gamepad Specification
---------------------------

:Author: 2013 by David Herrmann <dh.herrmann@gmail.com>


Introduction
~~~~~~~~~~~~
Linux provides many different input drivers for gamepad hardware. To avoid
having user-space deal with different button-mappings for each gamepad, this
document defines how gamepads are supposed to report their data.

Geometry
~~~~~~~~
As "gamepad" we define devices which roughly look like this::

            ____________________________              __
           / [__ZL__]          [__ZR__] \               |
          / [__ TL __]        [__ TR __] \              | Front Triggers
       __/________________________________\__         __|
      /                                  _   \          |
     /      /\           __             (N)   \         |
    /       ||      __  |MO|  __     _       _ \        | Main Pad
   |    <===DP===> |SE|      |ST|   (W) -|- (E) |       |
    \       ||    ___          ___       _     /        |
    /\      \/   /   \        /   \     (S)   /\      __|
   /  \________ | LS  | ____ |  RS | ________/  \       |
  |         /  \ \___/ /    \ \___/ /  \         |      | Control Sticks
  |        /    \_____/      \_____/    \        |    __|
  |       /                              \       |
   \_____/                                \_____/

       |________|______|    |______|___________|
         D-Pad    Left       Right   Action Pad
                 Stick       Stick

                   |_____________|
                      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,
    SOUTH, WEST and EAST.
  - D-Pad (Direction-pad)
    4 buttons (on the left side) that point up, down, left and right.
  - Menu-Pad
    Different constellations, but most-times 2 buttons: SELECT - START
    Furthermore, many gamepads have a fancy branded button that is used as
    special system-button. It often looks different to the other buttons and
    is used to pop up system-menus or system-settings.
  - Analog-Sticks
    Analog-sticks provide freely moveable sticks to control directions. Not
    all devices have both or any, but they are present at most times.
    Analog-sticks may also provide a digital button if you press them.
  - Triggers
    Triggers are located on the upper-side of the pad in vertical direction.
    Not all devices provide them, but the upper buttons are normally named
    Left- and Right-Triggers, the lower buttons Z-Left and Z-Right.
  - Rumble
    Many devices provide force-feedback features. But are mostly just
    simple rumble motors.

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.

Annotation

Implementation Notes