Overview: How the kernel reads raw keyboard hardware events, buffers keystrokes safely, stores files in a hierarchical tree in RAM, and runs an interactive Unix-like shell.
| Component | Source Link | What It Does | Why It Is Needed |
|---|---|---|---|
| PS/2 Controller Port | src/interrupts.rs:215 |
Reads raw scancodes from I/O port 0x60 |
Captures physical keypress events directly from the motherboard. |
| Keyboard Buffer & Sleep | src/keyboard.rs:8 |
Thread-safe ring buffer with hlt sleeping |
Decouples fast interrupt handling from user input consumption without burning 100% CPU time. |
| In-Memory VFS | src/fs.rs:19 |
Tree of Directory and File nodes |
Provides full file creation, writing, reading, and folder navigation in heap memory without requiring disk drivers. |
| Interactive Shell REPL | src/shell.rs:19 |
Runs as a preemptive kernel task | Provides a command-line interface supporting commands like ls, cat, touch, mkdir, cd, and pwd. |
| VGA Backspace Handling | src/vga_buffer.rs:95 |
Clears character cells and moves cursor backward | Ensures backspace visually erases characters on the screen while updating the command buffer. |
"Connecting keyboard hardware to an interactive shell requires building an end-to-end event and storage pipeline completely from scratch on bare metal.
When a physical key is pressed, the PS/2 keyboard controller triggers hardware IRQ 1 (Vector 33). In interrupts.rs, our keyboard interrupt handler reads the raw scancode byte from I/O port 0x60. Because keys send multiple scancodes for key press, key release, and modifier combinations like Shift and Caps Lock, we feed the raw bytes into a decoder. When a printable character or Enter key is resolved, it is pushed into a thread-safe circular input buffer in keyboard.rs, and an End-of-Interrupt signal is sent to the PIC.
The interactive shell runs as an independent preemptive kernel task. Rather than spinning in a busy-wait loop that burns CPU cycles, read_keyboard checks the input ring buffer: if empty, it executes the x86 hlt instruction to put the CPU into a low-power sleep state until the next timer tick or keypress wakes it up. It also synchronizes backspace between the text buffer and the screen so characters are properly erased visually.
For file management, I built an in-memory Hierarchical Virtual Filesystem (VFS) in fs.rs. It represents files and folders as a tree of nodes rooted at /, stored directly in heap memory. Path resolution parses strings by slashes, allowing navigation with cd (supporting both relative paths and ..), folder creation with mkdir, file creation with touch, reading with cat, and writing with write. This gives our bare-metal kernel a complete, interactive Unix-like user experience."
When the user presses a key on the keyboard, data flows through four distinct stages:
Physical Key Press
│
▼
Hardware IRQ 1 fires (PS/2 Controller)
│
▼
1. Interrupt Handler reads Port 0x60 (src/interrupts.rs:215)
- Gets raw byte scancode (e.g., 0x1E for 'A' pressed, 0x9E for 'A' released)
│
▼
2. Scancode Decoder (pc-keyboard crate)
- Tracks Shift, Caps Lock, and multi-byte escape sequences
- Converts valid scancodes into Unicode characters ('a', 'A', '\n', '\x08')
│
▼
3. Input Ring Buffer (src/keyboard.rs:8)
- Thread-safe Mutex-protected VecDeque<u8>
- Decouples interrupt handler from shell reader
│
▼
4. Shell Task reads buffer (src/keyboard.rs:23)
- If buffer has characters: pop, echo to VGA screen, and append to command line
- If buffer is empty: execute `hlt` to sleep efficiently until next interrupt
hlt Instead of Busy Waiting?If the shell ran a tight loop checking if buffer.is_empty(), the CPU would run at 100% capacity continuously, wasting host power and generating heat. By executing the x86 instruction hlt in src/keyboard.rs:23, the CPU immediately halts execution and enters low-power standby. The moment any hardware interrupt arrives (such as the keyboard IRQ or timer tick), the CPU wakes up, checks the buffer again, and continues execution with zero perceived lag.
Without hard drive drivers, all files and folders are stored dynamically inside kernel heap memory using recursive Rust structures defined in src/fs.rs:8:
Root Directory ("/")
├── File: "rust_rocks.txt" (data: "Systems programming in Rust is safe!")
└── Directory: "tests"
├── File: "output.log"
└── Directory: "subtests"
File: Contains a String name and a Vec<u8> storing raw file contents.Directory: Contains a name, a list of child files (Vec<File>), and a list of subdirectories (Vec<Directory>).FileSystem: Tracks the root directory and the current active working path (e.g., "/tests").When navigating paths in src/fs.rs:38 (get_current_directory_mut):
'/' delimiters into individual path components... by stripping the last component of the current path to navigate up one level.The shell loop in src/shell.rs:19 parses commands like ls, mkdir, touch, write, cat, cd, pwd, and shutdown using clean string pattern matching.
In early testing, pressing the Backspace key removed the last character from the internal command string buffer, but the character remained on the screen. The user couldn't tell what was currently in the buffer, leading to confusing typos.
To fix this, we implemented Writer::handle_backspace(). When backspace is pressed, the VGA driver checks if the cursor is past column 0, decrements the column index, writes a blank space (0x20) over the old character, and moves the cursor position back. This keeps the visual display and the in-memory string perfectly in sync.
Running the shell in QEMU and testing file creation, writing, and navigation:
Entering interactive shell. Type `help` for commands, or `exit` to quit.
/ >> touch rust_rocks.txt
File 'rust_rocks.txt' created.
/ >> write rust_rocks.txt Systems_programming_in_Rust_is_safe_and_fast!
Data written to file 'rust_rocks.txt'.
/ >> cat rust_rocks.txt
Content of 'rust_rocks.txt':
Systems_programming_in_Rust_is_safe_and_fast!
/ >> mkdir tests
Directory 'tests' created.
/ >> cd tests
Changed directory to '/tests'
/tests >> pwd
/tests
/tests >> cd ..
Changed directory to '/'
/ >> ls
Contents of '/':
[FILE] rust_rocks.txt
[DIR] tests
/ >>
This session verifies that the input buffer, text console, memory allocator, and filesystem work together cohesively.
hlt instruction instead of an empty while loop for keyboard input?Answer: "An empty while loop (while buffer.is_empty() {}) causes the CPU core to execute at 100% capacity doing useless checks, wasting host power and generating heat. The x86 hlt instruction puts the CPU core into a low-power sleep state until the next hardware interrupt (such as IRQ 1 from a keypress or IRQ 0 from the timer) occurs. This eliminates CPU waste while maintaining instant response times."
Answer: "The VFS is an in-memory filesystem stored entirely on the kernel heap. Directories and files are represented as recursive Rust structs (Vec<Directory> and Vec<File>). Our fixed-size block heap allocator dynamically allocates and grows memory for file contents as needed. This allows testing complete filesystem operations like creating, writing, and navigating files without needing ATA or AHCI disk drivers."
Answer: "A scancode is the raw hardware byte sent by the keyboard controller indicating a specific physical key switch on the board (e.g., 0x1E for the 'A' key), along with whether it was pressed or released. It does not know about capitalization or layout. An ASCII character is the decoded semantic meaning of that keypress after accounting for Shift state, Caps Lock, and keyboard layouts."