Chapter 45: Input subsystem¶

What: the input subsystem, the kernel framework that turns “a GPIO went low” or “an I²C read returned a touch coordinate” into a standardised event stream consumed by evdev, X11, Wayland, framebuffer toolkits, and command-line tools. A small button-driver case connects the IRQ handler to evtest reading /dev/input/eventN and contrasts it with the maintained gpio-keys driver. MCU bridge: Think of an IRQ like an EXTI/NVIC interrupt path, except Linux splits the hard interrupt from deferred work and must share lines across drivers. MCU bridge: Think of Linux GPIO like the same pin set/reset block you used on STM32, but accessed through a kernel subsystem that owns numbering, direction, interrupts, and user-space exposure. IRQ: interrupt request, the signal path that tells the CPU or interrupt controller that hardware needs service. GPIO: General-Purpose Input/Output, a pin controlled as a digital input, output, or interrupt source.

Why: every input device on a Linux box, keyboard, mouse, touchscreen, joystick, IR remote, goes through the input subsystem. Once you understand input_register_device and input_event, every input driver in the kernel looks familiar. The framework handles event multiplexing, queueing, sysfs/evdev integration, autorepeat, and userspace device-node creation, your driver just calls input_report_key() and input_sync(). sysfs: a kernel-generated filesystem under /sys that exposes devices, drivers, and attributes.

Focus: type, code, value, the three-element tuple that describes every input event. Once that triple makes sense, EV_KEY + KEY_ENTER + 1 means “Enter was pressed”, the rest of the input subsystem (abs axes, relative motion, multi-touch slots) is just different combinations of type/code/value.

45.1 The picture¶

When you press a key on a USB keyboard:

   physical key down
        │
   USB-HID interrupt-in transfer reports scan-code 0x28 (Enter)
        │
   usbhid driver: hid_input_report → input_report_key(dev, KEY_ENTER, 1)
        │
   input core:  queue an event {EV_KEY, KEY_ENTER, 1} on every evdev handler
        │
   /dev/input/event3 becomes readable
        │
   user-space: read() returns 24 bytes — a struct input_event
        │
   X11 / Wayland / your application: "Enter was pressed"

The driver’s only job is to call input_report_*() and input_sync(). The core handles queueing, multiplexing, and user-space delivery. Your driver feeds events into the type/code/value protocol. The input core delivers them to user-space. You never talk to user-space directly.

45.2 Event types and codes¶

Security boundary: Do not burn fuses, enroll production keys, or sign release images when exploring example code. Use throwaway keys and back up the unsigned image plus the key directory before testing irreversible security flows.

#include <linux/input.h>, defines hundreds of EV_*, KEY_*, BTN_*, ABS_*, REL_*, SW_*, LED_*, SND_*, MSC_* constants.

Common event types:

Type	Meaning	Typical codes
`EV_SYN`	Synchronization, end-of-event-group marker	`SYN_REPORT` (always 0)
`EV_KEY`	Key/button pressed/released	`KEY_A`…`KEY_Z`, `KEY_ENTER`, `BTN_LEFT`, `BTN_TOUCH`
`EV_REL`	Relative axis (mouse motion, scroll wheel)	`REL_X`, `REL_Y`, `REL_WHEEL`
`EV_ABS`	Absolute axis (touchscreen, joystick, IMU)	`ABS_X`, `ABS_Y`, `ABS_PRESSURE`, `ABS_MT_SLOT`
`EV_MSC`	Miscellaneous (scancode, raw value pass-through)	`MSC_SCAN`, `MSC_RAW`
`EV_SW`	Switch (lid open/closed, headphone jack, dock)	`SW_LID`, `SW_HEADPHONE_INSERT`
`EV_LED`	LED state output (driver consumes from userspace)	`LED_NUML`, `LED_CAPSL`
`EV_SND`	Sound output (PC speaker beep)	`SND_BELL`, `SND_TONE`

Each event has a value appropriate to its type:

EV_KEY value: 0 = released, 1 = pressed, 2 = autorepeat.
EV_REL value: signed delta (+1, -3, etc.).
EV_ABS value: absolute position, in whatever range the driver declared.
EV_SYN value: usually 0.

A coherent group of events ends with EV_SYN/SYN_REPORT. The input core delivers all events between two SYN_REPORTs atomically to userspace, important when a single touch update sends multiple coordinates that must arrive together.

45.3 The mainline `gpio-keys` driver¶

The kernel already has gpio-keys, the in-tree driver that exposes DT-described GPIOs as keyboard keys. It is the normal implementation choice when its capabilities match the product. The DT looks like this:

gpio_keys {
    compatible = "gpio-keys";

    key-enter {
        label = "Enter";
        linux,code = <KEY_ENTER>;
        gpios = <&gpio1 19 GPIO_ACTIVE_LOW>;
        debounce-interval = <50>;
        wakeup-source;
    };

    key-up {
        label = "Up";
        linux,code = <KEY_UP>;
        gpios = <&gpio4 14 GPIO_ACTIVE_LOW>;
        debounce-interval = <50>;
    };
};

Set CONFIG_KEYBOARD_GPIO=y in the kernel config, boot. Pressing the GPIO19 button now generates real KEY_ENTER events on /dev/input/eventN.

The smaller version below isolates the framework’s registration and reporting interfaces without requiring a separate implementation from the reader.

45.4 Writing our own button driver¶

button_input.c:

#include <linux/init.h>
#include <linux/module.h>
#include <linux/platform_device.h>
#include <linux/gpio/consumer.h>
#include <linux/input.h>
#include <linux/interrupt.h>

struct button_dev {
    struct input_dev *input;
    struct gpio_desc *gpio;
    int irq;
};

static irqreturn_t button_irq(int irq, void *dev_id)
{
    struct button_dev *bd = dev_id;
    int pressed = gpiod_get_value_cansleep(bd->gpio);
    /* The gpiod API has already applied ACTIVE_LOW polarity:
       pressed=1 here means logically pressed. */
    input_report_key(bd->input, KEY_ENTER, pressed);
    input_sync(bd->input);
    return IRQ_HANDLED;
}

static int button_probe(struct platform_device *pdev)
{
    struct button_dev *bd;
    int err;

    bd = devm_kzalloc(&pdev->dev, sizeof(*bd), GFP_KERNEL);
    if (!bd)
        return -ENOMEM;

    bd->gpio = devm_gpiod_get(&pdev->dev, "button", GPIOD_IN);
    if (IS_ERR(bd->gpio))
        return dev_err_probe(&pdev->dev, PTR_ERR(bd->gpio), "no button gpio\n");

    bd->irq = gpiod_to_irq(bd->gpio);
    if (bd->irq < 0)
        return bd->irq;

    bd->input = devm_input_allocate_device(&pdev->dev);
    if (!bd->input)
        return -ENOMEM;

    bd->input->name = "linuxlearn-button";
    bd->input->phys = "button/input0";
    bd->input->id.bustype = BUS_HOST;

    /* Declare what events this device can emit */
    input_set_capability(bd->input, EV_KEY, KEY_ENTER);

    err = input_register_device(bd->input);
    if (err)
        return dev_err_probe(&pdev->dev, err, "input register failed\n");

    err = devm_request_threaded_irq(&pdev->dev, bd->irq, NULL, button_irq,
                                     IRQF_TRIGGER_RISING | IRQF_TRIGGER_FALLING
                                     | IRQF_ONESHOT,
                                     "linuxlearn-button", bd);
    if (err)
        return err;

    platform_set_drvdata(pdev, bd);
    return 0;
}

static const struct of_device_id button_of_match[] = {
    { .compatible = "linuxlearn,input-button" },
    { }
};
MODULE_DEVICE_TABLE(of, button_of_match);

static struct platform_driver button_driver = {
    .driver = {
        .name = "linuxlearn-input-button",
        .of_match_table = button_of_match,
    },
    .probe = button_probe,
};
module_platform_driver(button_driver);

MODULE_LICENSE("GPL");

The flow:

devm_input_allocate_device() allocates an input_dev and ties its lifetime to the parent device.
We fill in identification, name (visible in evtest), phys (physical-bus path), id.bustype (origin family).
input_set_capability(input, EV_KEY, KEY_ENTER) declares “this device can emit EV_KEY events with code KEY_ENTER.” User-space tools query this via the EVIOCGBIT ioctl to learn what events to expect.
input_register_device() registers with the core. A /dev/input/eventN node appears.
In the IRQ handler, input_report_key() + input_sync() deliver one event.

DT:

my_button {
    compatible = "linuxlearn,input-button";
    button-gpios = <&gpio1 19 GPIO_ACTIVE_LOW>;
    pinctrl-names = "default";
    pinctrl-0 = <&pinctrl_button>;
};

Build, load:

[root@pa-mini:~]# insmod button_input.ko
[root@pa-mini:~]# cat /proc/bus/input/devices
I: Bus=0019 Vendor=0000 Product=0000 Version=0000
N: Name="linuxlearn-button"
P: Phys=button/input0
S: Sysfs=/devices/platform/my_button/input/input2
H: Handlers=evdev event2
B: PROP=0
B: EV=3
B: KEY=10000000 ... (sparse bit; KEY_ENTER is bit 28)

[root@pa-mini:~]# evtest /dev/input/event2
... waits ...
Press button: Event: time 4242.12, type 1 (EV_KEY), code 28 (KEY_ENTER), value 1
            Event: time 4242.12, ------------ SYN_REPORT -----------
Release:    Event: time 4242.45, type 1 (EV_KEY), code 28 (KEY_ENTER), value 0
            Event: time 4242.45, ------------ SYN_REPORT -----------

Done. Button is a real keyboard key.

45.5 Auto-repeat, debounce, and key mapping¶

The input core provides autorepeat for free: register EV_REP capability and the core will generate repeat events (value=2) while a key is held. gpio-keys does this automatically. Our minimal driver doesn’t bother.

Debounce filters electrical transitions into a stable logical state. A delayed-work design postpones sampling until the debounce interval has elapsed, then reports the stable press or release state. Further transitions restart the settling interval. The minimal driver above omits this policy, while gpio-keys provides debounce handling.

Key mapping. The KEY_* codes are logical, KEY_ENTER is the same value regardless of whether the user’s keymap is US QWERTY or Dvorak. The user-space keymap translates KEY_* to characters. For embedded devices with only a few buttons, you pick meaningful KEY_* codes:

KEY_VOLUMEUP / KEY_VOLUMEDOWN for media buttons.
KEY_POWER for the power button (the kernel and systemd both recognise this).
KEY_HOME, KEY_BACK, KEY_MENU for navigation.
KEY_WAKEUP for a wakeup-from-suspend button.

The full list is in include/uapi/linux/input-event-codes.h. Pick a code that matches the role of the button. User-space will know what to do with it.

45.6 Absolute axes, touchscreens and joysticks¶

For a touchscreen or joystick, you have coordinates, not key presses. Declare EV_ABS capabilities and report values:

input_set_abs_params(input, ABS_X, 0, 4095, 0, 0);
input_set_abs_params(input, ABS_Y, 0, 4095, 0, 0);
input_set_abs_params(input, ABS_PRESSURE, 0, 255, 0, 0);

/* In the IRQ/work handler when a sample arrives: */
input_report_abs(input, ABS_X, x_coord);
input_report_abs(input, ABS_Y, y_coord);
input_report_abs(input, ABS_PRESSURE, pressure);
input_report_key(input, BTN_TOUCH, 1);
input_sync(input);

input_set_abs_params(dev, code, min, max, fuzz, flat), min/max is the valid range, fuzz is the noise floor (changes ≤ fuzz are suppressed), flat is the center deadzone for joysticks.

For multi-touch, the protocol is more involved, the MT-B (slot-based) protocol uses ABS_MT_SLOT + per-finger ABS_MT_POSITION_X/Y. We’ll cover that in Ch 55G (GT911 multi-touch driver).

45.7 Polled vs interrupt-driven¶

Some input devices don’t have IRQs, accelerometers configured for continuous mode, for instance, or a button on a slow I²C expander where IRQ wiring isn’t practical. The input_polled_dev framework (now subsumed into the regular input_dev via input_setup_polling) polls a device at a fixed rate:

input_setup_polling(input, my_poll_callback);
input_set_poll_interval(input, 20);   /* 20 ms = 50 Hz */
input_register_device(input);

The core calls my_poll_callback(input) every 20 ms. Inside, sample the hardware, input_report_*, input_sync. No IRQ wiring needed.

45.8 User-space, evdev¶

/dev/input/event* is the chardev that streams struct input_event records to user-space:

struct input_event {
    struct timeval time;
    __u16 type;
    __u16 code;
    __s32 value;
};

Read one record per event. The most common tool is evtest (interactive) for debugging. For production, applications either use libevdev (a thin wrapper) or higher-level libraries:

libinput: used by Wayland and modern X11. Handles gesture recognition, palm rejection, tap-to-click, etc.
libevdev: minimal wrapper for reading raw events.
/dev/input/eventN directly: fine for embedded with one app.

For a quick test from shell:

$ sudo evtest /dev/input/event2     # interactive
$ sudo cat /dev/input/event2 | hexdump -C

45.9 Key Notes¶

An input driver translates device-specific observations into declared type/code/value events. Evdev and higher-level user-space consumers own delivery and interpretation.
Capabilities describe the device’s event vocabulary before registration. input_sync() marks the end of a coherent update, such as a key transition or coordinate sample.
Press and release are both state changes. Debounce and autorepeat are distinct policies, and a simple edge handler does not supply both automatically.
gpio-keys is an implementation choice, while the custom button case exposes the same architectural boundary with fewer features. Neither DT examples nor event listings qualify MINI wiring.
Logical key codes describe roles, not characters or mandatory system actions. Power-button shutdown policy belongs to the user-space system configuration.
IRQs, polling, and delayed work must stop reporting before the input device’s state is released. Framework registration does not remove the need for coordinated teardown.

45.10 Pitfalls¶

Forgetting input_sync. Events are buffered until SYN_REPORT. Without it, user-space never sees them. After any group of input_report_* calls, call input_sync.
Reporting an unsupported event. If you input_report_key(input, KEY_ENTER, 1) but didn’t input_set_capability(..., EV_KEY, KEY_ENTER), the event is silently dropped. Always declare capabilities first.
Not using devm_input_allocate_device. Forgetting input_free_device in error paths leaks the device. devm_ handles it.
Calling input_register_device before setting capabilities. Capabilities must be set before register. Order: alloc → set_capability → register.
Mixing input_allocate_device with separate input_register_device. Both can fail, at different points. Use standard goto cleanup, or just use devm_input_allocate_device to avoid the problem.
Confusing absolute and relative axes. Mice use EV_REL (delta motion). Touchscreens use EV_ABS (absolute position). Mixing them gives weird user-space behavior.
Multi-touch with single-touch protocol. Don’t try to emit ABS_X for multiple fingers, that’s not how it works. Use the MT-B slot protocol (Ch 55G).
Repeating events that haven’t actually changed. The core does not dedupe. Every input_report_key(..., 1) followed by input_sync is one event. Polling a held button without state-tracking spams the queue.
IRQ flag IRQF_TRIGGER_FALLING without IRQF_TRIGGER_RISING: you only get press events, not release. For a press/release-capable button, request both edges (IRQF_TRIGGER_RISING | IRQF_TRIGGER_FALLING).

45.11 Going deeper¶

Documentation/input/: the input subsystem’s full documentation. Read input.rst, event-codes.rst, multi-touch-protocol.rst.
include/uapi/linux/input-event-codes.h: the canonical list of EV_*, KEY_*, ABS_*, etc.
drivers/input/keyboard/gpio_keys.c: the in-tree gpio-keys driver. Read it. ~600 lines and covers debounce, wakeup, autorepeat, runtime PM, polling, every feature you’d add to a production button driver.
drivers/input/evdev.c: the evdev “handler” that exposes input events as /dev/input/eventN.
libevdev source (freedesktop.org), for high-level user-space input access.
Documentation/input/input.rst: overview of the input architecture, including the handler/handle/dev triangle.

Next chapter: Chapter 46: I²C drivers. With GPIO and input behind us, we move to a real bus: the i.MX6ULL’s I²C controllers, the i2c_client / i2c_driver model, and how a single I²C bus accommodates a half-dozen sensors at different addresses.