Vystem 0.2

docs/shelter/devs/abstracted/ps2.md

@@ -0,0 +1,36 @@
+# PS2 keyboard
+
+The PS2 keyboard driver is defined in `shelter/lib/include/devs/input/ps2.h` and implemented in `shelter/lib/src/devs/input/ps2.c`. This documentation only describes the public API, the one that is safe to access from external subsystems.
+
+## Driver initialization
+
+The PS2 is initialized using `sh_ps2_driver_init()`. The pre-requirement for this function include the keyboard input subsystem being initialized. Here is the exact procedure:
+1) Disable interrupts for safety
+2) Flush output buffer
+3) Debug log status and config byte initial value
+4) Disable keyboard and mouse PS2 ports
+5) Reflush output buffer for safety
+6) Disable both ports IRQs
+7) Perform the PS2 controller self test
+8) Enable port 1
+9) Enable scancodes translation
+10) Initialize driver internal state
+11) Enable IRQ for port 1
+12) Register interrupt handler for legacy IRQ1
+13) Enable interrupts
+14) Disable scanning
+15) Reset leds state
+16) Identify keyboard
+17) Register PS2 keyboard to the keyboard input subsystem
+18) Enable scanning
+
+For the moments, commands responses handling and scancodes parsing is working but there are a few limitations:
+- since we only parsed a few ACPI tables, we are unable to detect with certainty the presence of a PS2 controller. So the system consider that the PS2 controller is available and working and the keyboard device registered to the keyboard input subsystem will always be marked as present
+- any error in the driver initialization will be interpreted as a failure of the boot process
+- for the moment, we are unable to defer the leds state update when a scancode change the NumLock/CapsLock state, so these leds won't update
+
+## API
+
+A few additionnal functions are provided:
+- `sh_ps2_disable_scanning()`: disable PS2 keyboard scanning
+- `sh_ps2_enable_scanning()`: enable PS2 keyboard scanning