feat: add PS/2 keyboard interrupt driver by GloriousAlpaca · Pull Request #2532 · hermit-os/kernel

GloriousAlpaca · 2026-07-06T14:45:04Z

This feature adds support for the PS2 legacy keyboard in Qemu x86_64.
Currently it does:

A minimized hardware initialization (e.g. flush the output buffer) to use the keyboard, according to the standards for the Intel 8042 chip: Link to OSDev
Install an interrupt handler, which is done in the install_handlers function in interrupt.rs, as it is a hardware interrupt but does not belong in the pci interrupt handlers list (legacy device).
Add a systemcall to pop the last scancode out of the keyboard input ringbuffer (which currently has a length of 256). The Ringbuffer also uses Atomics, to prevent races and deadlocks.
The systemcall returns 0 if the keyboard feature is disabled.

I have only tested this feature with C programs on a Mac using Qemu.

github-actions

Benchmark Results

Details

Benchmark	Current: `2913b39`	Previous: `2e23902`	Performance Ratio
startup_benchmark Build Time	`80.60` s	`80.34` s	`1.00` ❗
startup_benchmark File Size	`0.76` MB	`0.80` MB	`0.95` ❗
Startup Time - 1 core	`0.73` s (`±0.02` s)	`0.75` s (`±0.02` s)	`0.97`
Startup Time - 2 cores	`0.74` s (`±0.02` s)	`0.74` s (`±0.02` s)	`1.00`
Startup Time - 4 cores	`0.74` s (`±0.02` s)	`0.74` s (`±0.02` s)	`1.00`
multithreaded_benchmark Build Time	`82.95` s	`82.11` s	`1.01` ❗
multithreaded_benchmark File Size	`0.90` MB	`0.86` MB	`1.05` ❗
Multithreaded Pi Efficiency - 2 Threads	`89.82` % (`±4.95` %)	`85.89` % (`±6.61` %)	`1.05`
Multithreaded Pi Efficiency - 4 Threads	`43.77` % (`±2.59` %)	`43.43` % (`±2.56` %)	`1.01`
Multithreaded Pi Efficiency - 8 Threads	`25.54` % (`±1.12` %)	`25.76` % (`±1.53` %)	`0.99`
micro_benchmarks Build Time	`79.85` s	`80.40` s	`0.99` ❗
micro_benchmarks File Size	`0.90` MB	`0.86` MB	`1.05` ❗
Scheduling time - 1 thread	`63.70` ticks (`±2.04` ticks)	`62.65` ticks (`±4.06` ticks)	`1.02`
Scheduling time - 2 threads	`35.09` ticks (`±4.97` ticks)	`34.08` ticks (`±4.10` ticks)	`1.03`
Micro - Time for syscall (getpid)	`3.49` ticks (`±0.57` ticks)	`3.45` ticks (`±0.58` ticks)	`1.01`
Memcpy speed - (built_in) block size 4096	`86814.64` MByte/s (`±59858.72` MByte/s)	`82448.38` MByte/s (`±56997.13` MByte/s)	`1.05`
Memcpy speed - (built_in) block size 1048576	`30713.15` MByte/s (`±24691.28` MByte/s)	`30585.98` MByte/s (`±24707.84` MByte/s)	`1.00`
Memcpy speed - (built_in) block size 16777216	`26832.08` MByte/s (`±22119.59` MByte/s)	`26340.06` MByte/s (`±21720.96` MByte/s)	`1.02`
Memset speed - (built_in) block size 4096	`86736.51` MByte/s (`±59800.76` MByte/s)	`82292.76` MByte/s (`±56891.50` MByte/s)	`1.05`
Memset speed - (built_in) block size 1048576	`31461.74` MByte/s (`±25133.14` MByte/s)	`31323.85` MByte/s (`±25145.86` MByte/s)	`1.00`
Memset speed - (built_in) block size 16777216	`27616.79` MByte/s (`±22621.64` MByte/s)	`27104.68` MByte/s (`±22209.94` MByte/s)	`1.02`
Memcpy speed - (rust) block size 4096	`77362.19` MByte/s (`±53838.02` MByte/s)	`74097.96` MByte/s (`±51811.44` MByte/s)	`1.04`
Memcpy speed - (rust) block size 1048576	`30568.62` MByte/s (`±24692.63` MByte/s)	`30361.60` MByte/s (`±24602.37` MByte/s)	`1.01`
Memcpy speed - (rust) block size 16777216	`27318.55` MByte/s (`±22610.97` MByte/s)	`27625.34` MByte/s (`±22806.88` MByte/s)	`0.99`
Memset speed - (rust) block size 4096	`78037.19` MByte/s (`±54279.16` MByte/s)	`74373.47` MByte/s (`±51976.48` MByte/s)	`1.05`
Memset speed - (rust) block size 1048576	`31316.06` MByte/s (`±25132.14` MByte/s)	`31110.89` MByte/s (`±25033.24` MByte/s)	`1.01`
Memset speed - (rust) block size 16777216	`28102.02` MByte/s (`±23103.52` MByte/s)	`28386.93` MByte/s (`±23265.03` MByte/s)	`0.99`
alloc_benchmarks Build Time	`76.08` s	`74.76` s	`1.02` ❗
alloc_benchmarks File Size	`0.84` MB	`0.87` MB	`0.96` ❗
Allocations - Allocation success	`91.31` %	`91.31` %	`1`
Allocations - Deallocation success	`100.00` %	`100.00` %	`1`
Allocations - Pre-fail Allocations	`61.44` %	`61.44` %	`1`
Allocations - Average Allocation time	`2384.40` Ticks (`±565.03` Ticks)	`5860.58` Ticks (`±98.43` Ticks)	`0.41` ❗
Allocations - Average Allocation time (no fail)	`3445.19` Ticks (`±482.39` Ticks)	`6554.81` Ticks (`±92.86` Ticks)	`0.53` ❗
Allocations - Average Deallocation time	`650.75` Ticks (`±148.28` Ticks)	`1805.01` Ticks (`±250.35` Ticks)	`0.36` ❗
mutex_benchmark Build Time	`78.56` s	`79.82` s	`0.98` ❗
mutex_benchmark File Size	`0.90` MB	`0.86` MB	`1.05` ❗
Mutex Stress Test Average Time per Iteration - 1 Threads	`11.92` ns (`±0.34` ns)	`12.10` ns (`±0.41` ns)	`0.99`
Mutex Stress Test Average Time per Iteration - 2 Threads	`38.94` ns (`±2.77` ns)	`40.26` ns (`±1.68` ns)	`0.97`

This comment was automatically generated by workflow using github-action-benchmark.

mkroening

Thanks for the PR! :)

I was wondering why implement drivers for legacy devices instead of USB keyboards (xhci, usb-oxide, embassy-usb). I guess it is because of simplicity.

It would be great to discuss the high-level application-facing API, since that is the hardest to change once merged.

mkroening · 2026-07-07T13:28:41Z

+## Enables the PS/2 keyboard driver.
+##
+## This is only useful on PCs (x86-64).
+keyboard = []   


Could you rename this to pc-keyboard? Also, please make sure that the docs don't imply that this is needed for keyboard support in general. Serial-based keyboard support is separate from this. Similar to the framebuffer, please also put a disclaimer that this does not make the kernel use the driver and instead exposes an API for applications that need to be ported.

mkroening · 2026-07-07T13:30:39Z

 }

-pub(crate) fn install_handlers(handlers: InterruptHandlerMap) {
+pub(crate) fn install_handlers(#[allow(unused_mut)] mut handlers: InterruptHandlerMap) {


Please move the allow to the function level instead of having it inline like this.

mkroening · 2026-07-07T13:45:46Z

+		data_port.write(config);
+		cmd_port.write(PS2_CMD_ENABLE_KEYBOARD);
+	}
+	fn keyboard_handler() {


Please move the handler to the top level outside of this function.

mkroening · 2026-07-07T13:47:07Z

+		while (cmd_port.read() & PS2_BUFFER_FULL) != 0 {
+			let _ = data_port.read();
+		}


Why do we discard the device buffer instead of filling our read buffer?

At the start there might be garbage data in the output buffer, that can get stuck if we don't clear it.

https://wiki.osdev.org/I8042_PS/2_Controller#Step_4:_Flush_The_Output_Buffer

mkroening · 2026-07-07T13:52:13Z

+		let mut cmd_port = Port::<u8>::new(PS2_CMD_PORT);
+		let mut data_port = Port::<u8>::new(PS2_DATA_PORT);


Do you think an abstraction similar to the proposal for BGA would make sense?

struct Ps2; impl Ps2 { fn read_data() -> u8; fn write_data(data: u8); fn status() -> u8; fn command(command: u8); }

mkroening · 2026-07-07T14:02:27Z

+/// Pops a scancode from the keyboard buffer, returning None if the buffer is empty.
+pub fn pop_scancode() -> Option<u8> {


A scancode can never be zero, right? Returning Option<NonZero<u8>> would be preferable in that case.

mkroening · 2026-07-07T14:08:41Z

+#[cfg(all(target_arch = "x86_64", feature = "keyboard"))]
+#[hermit_macro::system]
+#[unsafe(no_mangle)]
+pub extern "C" fn sys_read_keyboard() -> u8 {
+	crate::kernel::keyboard::pop_scancode().unwrap_or(0)
+}


I am not too sure about this API. Is the application supposed to busy loop on this and retrieve one event at a time?

What about doing something similar to Linux's event device (evdev) interface (Linux docs)? Reading from /dev/input/event0 would then fill a user buffer with input events and blocks if no events are there unless opened with O_NONBLOCK.

Since we don't use a filesystem like Linux I would propose something like this:
pub extern "C" fn sys_read_keyboard(buffer: *mut u8 ,size: usize, nonblock: bool) -> isize
(Should I also rename the systemcall to sys_read_pc_keyboard?)
This would be pretty flexible, we can throw standard errorcodes or return the buffersize in bytes like this.
We can then use a semaphore to block the thread until there are scancodes in the vecdeque.

jounathaen · 2026-07-24T10:29:11Z

+struct Ps2;
+


Suggested change

struct Ps2;

struct Ps2;

Small nitpick

jounathaen · 2026-07-24T10:30:48Z

+		let mut status_port = Port::<u8>::new(PS2_CMD_PORT);
+		unsafe { status_port.read() }


Suggested change

let mut status_port = Port::<u8>::new(PS2_CMD_PORT);

unsafe { status_port.read() }

unsafe { Port::<u8>::new(PS2_CMD_PORT).read() }

jounathaen · 2026-07-24T12:29:16Z

+const PS2_CMD_READ_CNFG: u8 = 0x20;
+const PS2_CMD_WRITE_CNFG: u8 = 0x60;
+const PS2_CMD_DISABLE_KEYBOARD: u8 = 0xad;
+const PS2_CMD_DISABLE_MOUSE: u8 = 0xa7;
+const PS2_CMD_ENABLE_KEYBOARD: u8 = 0xae;


Also here, this looks like an enum for me in conjunction with the read_cmd/write_cmd functions.

jounathaen · 2026-07-24T12:31:59Z

+	let scancode = Ps2::read_data();
+	let mut buffer = KEYBOARD_BUFFER.lock();
+
+	if buffer.len() >= BUFFER_SIZE {
+		buffer.pop_front();
+	}
+	buffer.push_back(scancode);


I wonder if retaining the keys in the queue is how this is handled best. I'm thinking that maybe adding a timestamp to each key event and discarding it after x seconds is a correct approach. But maybe I'm prematurely optimizing this. It would be interesting to know how other systems are handling this.

jounathaen · 2026-07-24T12:33:03Z

+## 
+## This feature initializes the PS/2 keyboard controller and installs a keyboard interrupt handler. 
+## It also provides a system call to receive the last scancode from the internal keyboard buffer. 
+## Note that this is not a complete keyboard driver and not needed for general keyboard support.


Suggested change

## Note that this is not a complete keyboard driver and not needed for general keyboard support.

## Note that this is not a complete keyboard driver and not needed for serial input/output.

mkroening self-assigned this Jul 6, 2026

GloriousAlpaca force-pushed the pr-keyboard-clean branch from 7c21b3f to 5d35a06 Compare July 6, 2026 15:33

github-actions Bot reviewed Jul 6, 2026

View reviewed changes

GloriousAlpaca force-pushed the pr-keyboard-clean branch 2 times, most recently from 2c424d5 to f6c859b Compare July 6, 2026 16:30

mkroening requested changes Jul 7, 2026

View reviewed changes

GloriousAlpaca force-pushed the pr-keyboard-clean branch from f6c859b to 0a1c568 Compare July 15, 2026 12:53

feat: add PS/2 keyboard interrupt driver

4db677f

GloriousAlpaca force-pushed the pr-keyboard-clean branch from 0a1c568 to a7180a7 Compare July 15, 2026 14:21

refactor: rename ps2 keyboard driver to pc-keyboard

153302f

GloriousAlpaca force-pushed the pr-keyboard-clean branch from a7180a7 to 153302f Compare July 17, 2026 14:24

Andreas Wessing added 2 commits July 21, 2026 17:32

refactor: use mutex with vecdeque instead of atomic ringbuffer

df6d5cf

refactor: ps2 controller port access abstraction

68d8082

mkroening requested review from jounathaen and sarahspberrypi July 23, 2026 15:32

jounathaen reviewed Jul 24, 2026

View reviewed changes

style: change abstraction functions to oneliners

2913b39

GloriousAlpaca force-pushed the pr-keyboard-clean branch from 3473d4f to 2913b39 Compare July 24, 2026 12:37

		let mut cmd_port = Port::<u8>::new(PS2_CMD_PORT);
		let mut data_port = Port::<u8>::new(PS2_DATA_PORT);

		/// Pops a scancode from the keyboard buffer, returning None if the buffer is empty.
		pub fn pop_scancode() -> Option<u8> {

		let mut status_port = Port::<u8>::new(PS2_CMD_PORT);
		unsafe { status_port.read() }

	let mut status_port = Port::<u8>::new(PS2_CMD_PORT);
	unsafe { status_port.read() }
	unsafe { Port::<u8>::new(PS2_CMD_PORT).read() }

	## Note that this is not a complete keyboard driver and not needed for general keyboard support.
	## Note that this is not a complete keyboard driver and not needed for serial input/output.

Uh oh!

Conversation

GloriousAlpaca commented Jul 6, 2026

Uh oh!

github-actions Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Benchmark Results

Uh oh!

mkroening left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot left a comment •

edited

Loading