boredos_mirror/docs/architecture/input/keyboard.md

Input Subsystem

Overview

The input subsystem is responsible for handling user input, primarily from the keyboard.

It provides a structured pipeline that transforms low-level hardware signals into usable data for the kernel and higher-level components. This subsystem abstracts hardware-specific behavior and exposes a consistent interface to the rest of the operating system.

---

Scope

The /input directory focuses on keyboard input. It includes:

• A keyboard driver responsible for handling hardware events
• A keycode layer used as an intermediate representation
• A keymap system that translates keycodes into characters

---

Design Principles

• Hardware abstraction
  Hardware-specific logic is isolated from higher-level components.

• Simplicity
  The input path is kept minimal and efficient, especially in interrupt context.

• Modularity
  Each stage of input processing is handled by a dedicated component.

• Extensibility
  The system is designed to support additional input devices and layouts in the future.

---

Directory Structure

input/
├── keyboard.c
├── keyboard.h
├── keycodes.h
├── keymap.c
├── keymap.h

---

Input Processing Model

Keyboard input is processed in three distinct stages:

1. Raw scancodes are received from the hardware
2. Scancodes are converted into keycodes
3. Keycodes are translated into characters or control signals

Each stage is handled independently to ensure clarity and maintainability.

---

Components

Keyboard Driver

Overview

The keyboard driver interfaces directly with the keyboard hardware. It handles interrupts and processes raw input data from the controller.

Responsibilities

• Handle keyboard interrupts
• Read scancodes from the PS/2 controller
• Convert scancodes into keycodes
• Forward processed data to higher layers

Behavior

The driver operates in an interrupt-driven context. When a key event occurs, the hardware triggers an interrupt. The driver reads the corresponding scancode and processes it immediately.

Because this code runs at a low level, it must be fast, predictable, and minimal.

Integration

The keyboard driver depends on:

• The PS/2 controller driver for hardware communication
• The interrupt subsystem for event handling

It provides output to:

• The keycode system
• The keymap system

Constraints

• Must not block execution
• Must minimize processing time per interrupt
• Must correctly handle key press and key release events

---

Keycodes

Overview

Keycodes define a hardware-independent representation of keyboard keys.

They serve as an abstraction layer between raw scancodes and higher-level logic.

Purpose

The keycode system standardizes keyboard input by mapping all physical key events to a consistent set of identifiers.

This allows the system to:

• Remain independent from specific hardware implementations
• Simplify input handling logic
• Support multiple layouts and configurations

Design

Each key is represented by a unique constant, such as:

• KEY_A
• KEY_ENTER
• KEY_SHIFT

Role in the System

Keycodes act as the intermediate layer between:

• Hardware-level scancodes
• Character-level or command-level input

Usage

• Generated by the keyboard driver
• Consumed by the keymap system

Extensibility

The keycode system can be extended to support:

• Additional keys (function keys, multimedia keys)
• Non-standard input devices
• Custom mappings

---

Keymap

Overview

The keymap system translates keycodes into characters or control signals.

It defines how physical key presses are interpreted based on layout and modifier state.

Responsibilities

• Convert keycodes into ASCII or equivalent representations
• Apply modifier logic such as Shift and Control
• Provide consistent character output

Behavior

The keymap takes a keycode as input and produces an output depending on:

• The current keyboard layout
• Active modifier keys

The same keycode may produce different results depending on modifier state.

Integration

• Receives keycodes from the keyboard driver
• Outputs characters to the kernel or userland

---

Control Signals

In addition to character generation, the input subsystem produces control signals representing non-printable keys and command-oriented input.

These signals are derived from keycodes that do not map directly to ASCII characters.

---

Definition

A control signal is an abstract representation of a key event used to trigger system-level behavior rather than text output.

Typical control signals include:

• Enter
• Backspace
• Escape
• Tab
• Arrow keys
• Function keys

---

Encoding

Control signals may be represented in different ways depending on the layer:

ASCII Control Characters (when applicable)

Some keys map to standard ASCII control codes:

• ENTER → 0x0A (Line Feed) or 0x0D (Carriage Return)
• BACKSPACE → 0x08
• TAB → 0x09
• ESC → 0x1B

These values are part of the ASCII control range (0x00–0x1F).

---

Non-ASCII Keys

Keys that do not belong to the ASCII set are typically handled as extended keycodes or internal constants:

Examples:

• Arrow keys
• Insert / Delete
• Home / End
• Function keys (F1–F12)

---

Non-ASCII Characters

Non-ASCII characters include any character outside the standard 7-bit ASCII range (0x00–0x7F).

Examples:

• Accented characters: é, à, ç
• Symbols: €, £
• Unicode characters from non-Latin scripts

---

Encoding Considerations

The current system typically assumes ASCII output. However, supporting non-ASCII characters requires:

• A wider character encoding (e.g. UTF-8)
• Extended keymaps capable of mapping key combinations to multi-byte sequences

Example:

• 'é' in UTF-8 → 0xC3 0xA9

---

Modifier and Layout Impact

Non-ASCII characters are often produced through:

• Keyboard layout differences (AZERTY vs QWERTY)
• Modifier combinations (Shift, AltGr)

Example:

• AltGr + E → '€' (depending on layout)
• KEY_E → 'e'
• KEY_E + SHIFT → 'E'

---

Usage

• Control signals are used for command handling and system interaction
• Non-ASCII characters are used for text input and require proper encoding support