Linux Input Subsystem Introduction

Input subsystem 구조

Linux input subsystem은 모든 입력 장치를 지원하도록 설계된 driver 모음입니다. 대부분은 `drivers/input`에 있지만 상당수는 `drivers/hid`와 `drivers/platform`에도 있습니다.

중심인 `input` module은 다른 input module보다 먼저 load되어야 하며 device driver와 event handler 두 module 그룹 사이의 통신 경로 역할을 합니다.

Device driver는 USB 같은 방식으로 hardware와 통신하고 keystroke나 mouse movement event를 input module에 제공합니다. Event handler는 input core에서 event를 받아 kernel keyboard 처리, GPM과 X를 위한 가상 PS/2 mouse interface 등 필요한 대상으로 전달합니다.

.. include:: <isonum.txt>

============
Introduction
============

:Copyright: |copy| 1999-2001 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE

Architecture
============

Input subsystem is a collection of drivers that is designed to support
all input devices under Linux. Most of the drivers reside in
drivers/input, although quite a few live in drivers/hid and
drivers/platform.

The core of the input subsystem is the input module, which must be
loaded before any other of the input modules - it serves as a way of
communication between two groups of modules:

Device drivers
--------------

These modules talk to the hardware (for example via USB), and provide
events (keystrokes, mouse movements) to the input module.

Event handlers
--------------

These modules get events from input core and pass them where needed
via various interfaces - keystrokes to the kernel, mouse movements via
a simulated PS/2 interface to GPM and X, and so on.

USB keyboard와 mouse의 기본 구성

USB mouse 하나와 USB keyboard 하나인 일반 구성에서는 `input`, `mousedev`, `usbcore`, UHCI·OHCI·EHCI 중 해당 host controller driver, `usbhid`, `hid_generic` module을 load하거나 kernel에 내장해야 합니다.

그러면 USB keyboard는 바로 동작하고 USB mouse는 major 13, minor 63인 `/dev/input/mice` character device로 제공됩니다. 보통 system이 자동 생성하지만 수동으로는 `/dev/input`을 만들고 `mknod input/mice c 13 63`을 실행합니다.

GPM은 `gpm -t ps2 -m /dev/input/mice`로 시작하고 XFree의 Pointer section에는 `Protocol "ImPS/2"`, `Device "/dev/input/mice"`, `ZAxisMapping 4 5`를 설정합니다.

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)::

        input
        mousedev
        usbcore
        uhci_hcd or ohci_hcd or ehci_hcd
        usbhid
        hid_generic

After this, the USB keyboard will work straight away, and the USB mouse
will be available as a character device on major 13, minor 63::

        crw-r--r--   1 root     root      13,  63 Mar 28 22:45 mice

This device is usually created automatically by the system. 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::

        gpm -t ps2 -m /dev/input/mice

And in X::

        Section "Pointer"
            Protocol    "ImPS/2"
            Device      "/dev/input/mice"
            ZAxisMapping 4 5
        EndSection

When you do all of the above, you can use your USB mouse and keyboard.

Event handler와 evdev

Event handler는 device event를 필요에 따라 사용자 공간과 kernel 내부 consumer에 배포합니다.

`evdev`는 generic input event interface입니다. Kernel에서 생성된 event를 timestamp와 함께 프로그램에 그대로 전달하며 event code는 모든 architecture에서 같고 hardware 독립적입니다. 사용자 공간이 사용자 입력을 소비할 때 권장되는 interface이므로 모든 client가 이를 사용하도록 권장합니다.

Evdev device는 `/dev/input/event0`, `event1`처럼 나타납니다. Minor 64~95는 정적 legacy 범위이며 input device가 32개보다 많으면 minor 256부터 추가 node를 만듭니다.

Detailed Description
====================

Event handlers
--------------

Event handlers distribute the events from the devices to userspace and
in-kernel consumers, as needed.

evdev
~~~~~

``evdev`` is the generic input event interface. It passes the events
generated in the kernel straight to the program, with timestamps. The
event codes are the same on all architectures and are hardware
independent.

This is the preferred interface for userspace to consume user
input, and all clients are encouraged to use it.

See :ref:`event-interface` for notes on API.

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
        crw-r--r--   1 root     root      13,  66 Apr  1 10:50 event2
        crw-r--r--   1 root     root      13,  67 Apr  1 10:50 event3
        ...

There are two ranges of minors: 64 through 95 is the static legacy
range. If there are more than 32 input devices in a system, additional
evdev nodes are created with minors starting with 256.

Keyboard, mousedev와 joydev handler

`keyboard`는 VT code의 일부인 kernel 내부 input handler로 keyboard keystroke를 소비해 VT console의 사용자 입력을 처리합니다.

`mousedev`는 mouse input을 사용하는 legacy program을 위한 호환 계층입니다. Mouse나 digitizer·tablet event를 받아 `/dev/psaux`와 같은 PS/2-style mouse device로 사용자 공간에 제공합니다.

각 `/dev/input/mouseN`은 한 mouse 또는 digitizer에 대응하지만 마지막 `/dev/input/mice`는 모든 mouse와 digitizer가 공유하며 장치가 없어도 존재합니다. 따라서 hotplug를 모르는 오래된 프로그램도 mouse가 없는 때 미리 열어 둘 수 있습니다.

`CONFIG_INPUT_MOUSEDEV_SCREEN_X/Y`는 digitizer 좌표를 virtual PS/2 mouse movement로 XFree86 화면에 맞춰 scale할 때 쓰는 pixel 크기입니다. Mouse만 사용하면 적용되지 않습니다.

Mousedev는 reader 요청에 따라 PS/2, wheel을 지원하는 ImPS/2, 최대 5개 추가 button을 지원하는 ExplorerPS/2 protocol을 생성합니다. GPM과 X는 이 중 원하는 protocol로 설정할 수 있습니다.

`joydev`는 Linux joystick API v0.x와 v1.x를 구현합니다. Joystick은 `/dev/input/js0`부터 나타나며 legacy 범위는 `js31`까지이고 장치가 더 많으면 minor 256 이상을 사용합니다.

keyboard
~~~~~~~~

``keyboard`` is in-kernel input handler and is a part of VT code. It
consumes keyboard keystrokes and handles user input for VT consoles.

mousedev
~~~~~~~~

``mousedev`` is a hack to make legacy programs that use mouse input
work. It takes events from either mice or digitizers/tablets and makes
a PS/2-style (a la /dev/psaux) mouse device available to the
userland.

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
        crw-r--r--   1 root     root      13,  34 Mar 29 00:41 mouse2
        crw-r--r--   1 root     root      13,  35 Apr  1 10:50 mouse3
        ...
        ...
        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
mice and digitizers, and even if none are connected, the device is
present.  This is useful for hotplugging USB mice, so that older programs
that do not handle hotplug can open the device even when no mice are
present.

CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
the size of your screen (in pixels) in XFree86. This is needed if you
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
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.

joydev
~~~~~~

``joydev`` implements v0.x and v1.x Linux joystick API. See
:ref:`joystick-api` for details.

As soon as any joystick is connected, it can be accessed in /dev/input on::

        crw-r--r--   1 root     root      13,   0 Apr  1 10:50 js0
        crw-r--r--   1 root     root      13,   1 Apr  1 10:50 js1
        crw-r--r--   1 root     root      13,   2 Apr  1 10:50 js2
        crw-r--r--   1 root     root      13,   3 Apr  1 10:50 js3
        ...

And so on up to js31 in legacy range, and additional nodes with minors
above 256 if there are more joystick devices.

주요 input device driver

Device driver는 input event를 생성하는 module입니다. `hid-generic`은 HID 장치 종류가 매우 많고 USB HID specification이 복잡해 input suite에서 가장 크고 복잡한 driver 중 하나입니다.

현재 USB mouse, joystick, gamepad, steering wheel, keyboard, trackball과 digitizer를 처리합니다. USB HID는 monitor·speaker control, UPS, LCD 등에도 쓰입니다. Monitor·speaker control은 hid/input에 연결하기 쉽지만 UPS와 LCD에는 적합하지 않아 `hiddev` interface가 마련됐으며 자세한 내용은 `Documentation/hid/hiddev.rst`에 있습니다.

`usbhid`는 parameter 없이 자동 탐지합니다. 장치 편차 때문에 잘 동작하지 않는 경우 문서는 `hid-core.c` 시작 부분의 `DEBUG`를 정의하고 syslog trace를 보내라고 안내합니다.

`usbmouse`는 embedded system, 잘못된 HID descriptor를 가진 mouse, 큰 usbhid가 부적합한 경우를 위한 USB mouse 전용 driver입니다. 단순 HIDBP protocol을 사용하므로 장치가 이를 지원해야 하며 특별한 이유가 없으면 usbhid를 사용합니다.

`usbkbd`도 단순 HIDBP protocol로 keyboard와 통신해 작지만 extra special key를 지원하지 않습니다. 특별한 이유가 없으면 usbhid가 권장됩니다.

`psmouse`는 Synaptics·ALPS touchpad, Intellimouse Explorer, Logitech PS/2 mouse 등 모든 PS/2 pointing device를 처리합니다. `atkbd`는 PS/2(AT) keyboard driver입니다.

`iforce`는 USB와 RS232를 통한 I-Force joystick·wheel driver이며 force feedback도 지원합니다.

Device drivers
--------------

Device drivers are the modules that generate events.

hid-generic
~~~~~~~~~~~

``hid-generic`` is one of the largest and most complex driver of the
whole suite. It handles all HID devices, and because there is a very
wide variety of them, and because the USB HID specification isn't
simple, it needs to be this big.

Currently, it handles USB mice, joysticks, gamepads, steering wheels,
keyboards, trackballs and digitizers.

However, USB uses HID also for monitor controls, speaker controls, UPSs,
LCDs and many other purposes.

The monitor and speaker controls should be easy to add to the hid/input
interface, but for the UPSs and LCDs it doesn't make much sense. For this,
the hiddev interface was designed. See Documentation/hid/hiddev.rst
for more information about it.

The usage of the usbhid module is very simple, it takes no parameters,
detects everything automatically and when a HID device is inserted, it
detects it appropriately.

However, because the devices vary wildly, you might happen to have a
device that doesn't work well. In that case #define DEBUG at the beginning
of hid-core.c and send me the syslog traces.

usbmouse
~~~~~~~~

For embedded systems, for mice with broken HID descriptors and just any
other use when the big usbhid wouldn't be a good choice, there is the
usbmouse driver. It handles USB mice only. It uses a simpler HIDBP
protocol. This also means the mice must support this simpler protocol. Not
all do. If you don't have any strong reason to use this module, use usbhid
instead.

usbkbd
~~~~~~

Much like usbmouse, this module talks to keyboards with a simplified
HIDBP protocol. It's smaller, but doesn't support any extra special keys.
Use usbhid instead if there isn't any special reason to use this.

psmouse
~~~~~~~

This is driver for all flavors of pointing devices using PS/2
protocol, including Synaptics and ALPS touchpads, Intellimouse
Explorer devices, Logitech PS/2 mice and so on.

atkbd
~~~~~

This is driver for PS/2 (AT) keyboards.

iforce
~~~~~~

A driver for I-Force joysticks and wheels, both over USB and RS232.
It includes Force Feedback support now, even though Immersion
Corp. considers the protocol a trade secret and won't disclose a word
about it.

동작 검증과 `input_event` interface

Keyboard는 몇 key를 입력해 kernel keyboard driver 연결을 확인합니다. Mouse emulation은 `cat /dev/input/mouse0`에서 mouse를 움직일 때 문자가 나타나는지 봅니다. Joystick emulation은 joystick package의 `jstest`, event device는 `evtest`로 시험합니다.

`/dev/input/eventX`에서는 blocking·nonblocking read와 `select()`를 사용할 수 있고 한 번의 read는 항상 `struct input_event`의 정수 개를 반환합니다.

`struct input_event`는 event 발생 시각인 `struct timeval time`, event type인 `unsigned short type`, event code인 `unsigned short code`, 전달값인 `int value`로 구성됩니다.

`type`은 상대 이동 `EV_REL`, key press·release `EV_KEY` 등이며 전체 type은 `include/uapi/linux/input-event-codes.h`에 있습니다. `code`는 `REL_X`, `KEY_BACKSPACE` 같은 세부 code이고 같은 header에 전체 목록이 있습니다.

`value`는 `EV_REL`의 상대 변화량, `EV_ABS`의 절대 새 값, `EV_KEY`의 release 0, press 1, autorepeat 2입니다. 여러 event code의 의미는 `input-event-codes` 문서를 참고합니다.

Verifying if it works
=====================

Typing a couple keys on the keyboard should be enough to check that
a keyboard works and is correctly connected to the kernel keyboard
driver.

Doing a ``cat /dev/input/mouse0`` (c, 13, 32) will verify that a mouse
is also emulated; characters should appear if you move it.

You can test the joystick emulation with the ``jstest`` utility,
available in the joystick package (see :ref:`joystick-doc`).

You can test the event devices with the ``evtest`` utility.

.. _event-interface:

Event interface
===============

You can use blocking and nonblocking reads, and also select() on the
/dev/input/eventX devices, and you'll always get a whole number of input
events on a read. Their layout is::

    struct input_event {
            struct timeval time;
            unsigned short type;
            unsigned short code;
            int value;
    };

``time`` is the timestamp, it returns the time at which the event happened.
Type is for example EV_REL for relative movement, 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
list is in include/uapi/linux/input-event-codes.h.

``value`` is the value the event carries. Either a relative change for
EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
release, 1 for keypress and 2 for autorepeat.

See :ref:`input-event-codes` for more information about various even codes.