# Keyboard input subsystem ## Introduction The keyboard input subsystem is responsible for abstracting keyboard devices and keyboards events. It's defined in `shelter/lib/include/devs/input/kbd.h` and implemented in `shelter/lib/src/devs/input/kbd.c`. It's still in the early stage and isn't finished for the moment. ## Overview The keyboard input subsystem is based on two key concepts: - keyboard devices: this is the standard abstraction for any keyboard-like devices - keyboard events: provides a standard way to interpret any events from any keyboard devices The keyboard input subsystem is initialized using `sh_kbd_init_devs()`. ### Keyboard devices ### Driver side The keyboard device structure look like this: ``` C typedef struct { sh_uint8 kbd_id; sh_queue_KBD_EVENT *events_queue; sh_bool present; sh_bool ver_maj; sh_bool ver_num; sh_bool shift; sh_bool alt; sh_bool ctrl; sh_bool win; sh_SPIN_LOCK spinlock; } sh_kbd_DEVICE; ``` Each keyboard device is identified with a keyboard id. When a keyboard is unregistered, the keyboard id can be recycled for a new keyboard device. There is a maximum of 256 keyboards id, and so 256 maximum registered keyboard devices at the same time. The keyboard id 0 is reserved for the PS2 keyboard. It's always valid, even if there is no PS2 controller. The `present` boolean defines if the keyboard is present. If `present` is `SH_FALSE`, no actions except unregistering the keyboard is allowed on the keyboard device. The `present` boolean for the keyboard od keyboard id 0 indicates if the PS2 controller is available. There is two primitives to register keyboards devices: - `sh_kbd_register_ps2(sh_bool is_present,sh_kbd_DRIVER_HANDLE **handle)`: register the PS2 keyboard, reserved for the PS2 driver - `sh_kbd_register(sh_bool is_present,sh_kbd_DRIVER_HANDLE **handle)`: register a new keyboard device Upon registration, a `sh_kbd_DRIVER_HANDLE` struct is completed. It became non valid when the keyboard is unregistered. It is reserved for driver usage only. Two primitives accessible to drivers require this driver handle: - `sh_kbd_set_flag(sh_kbd_DRIVER_HANDLE *handle,sh_uint8 flag,sh_bool value)`: set a flag about the keyboard corresponding to the provided driver handle - `sh_kbd_push_events(sh_kbd_DRIVER_HANDLE *handle,sh_kbd_EVENT *event)`: push an event in the events queue of the keyboard device corresponding to the provided driver handle There is, for the moment, no primitive to unregister a keyboard. ### Consumer side Four functions are available for consumers: - `sh_kbd_enumerate_devices(sh_kbd_ENUMERATION *enumeration)`: complete a `sh_kbd_ENUMERATION` structure, each bit set to 1 correspond to a valid keyboard id - `sh_kbd_get_handle(sh_uint8 kbd_id,sh_kbd_CONSUMER_HANDLE **handle)`: return a valid consumer handle for the provided keyboard id. It uses `sh_malloc` - `sh_kbd_destroy_handle(sh_kbd_CONSUMER_HANDLE **handle)`: free the provided consumer handle - `sh_kbd_read_flag(sh_kbd_DRIVER_HANDLE *d_handle,sh_kbd_CONSUMER_HANDLE *c_handle,sh_uint8 flag,sh_bool *value)`: read a flag about the keyboard corresponding to the provided handle. Accepts either a driver or consumer handle, but fails if both handle are provided. The possible flags to read/write are: `SH_KBD_FLAG_PRESENT`, `SH_KBD_FLAG_VER_MAJ`, `SH_KBD_FLAG_VER_NUM`, `SH_KBD_FLAG_SHIFT`, `SH_KBD_FLAG_ALT`, `SH_KBD_FLAG_CTRL`, `SH_KBD_FLAG_WIN`. There is, for the moment, no way to read keyboards events. ## Keyboard events A keyboard event is represented by this structure: ``` C typedef struct { sh_uint16 scancode; sh_bool pressed; sh_uint8 context_shift_win; sh_uint8 context_alt; sh_uint8 context_ctrl; sh_uint8 context_lock_status; sh_uint8 event_type; sh_uint64 timestamp; } sh_kbd_EVENT; ``` All non-pause events contain a snapshot of keyboard context state at emission time, before the state of corresponding flag in the keyboard device changes. These fields remain valid even for `SH_EVENT_TYPE_KBD_CONTEXT`: - `context_shift_win`: - Bit 0: shift active, checked with macro `SH_KBD_EVENT_SHIFT_ACTIVE` - Bit 1: win active, checked with macro `SH_KBD_EVENT_WIN_ACTIVE` - `context_alt`: - Bit 0: right alt active, checked with macro `SH_KBD_EVENT_RIGHT_ACTIVE` - Bit 1: left alt active, checked with macro `SH_KBD_EVENT_LEFT_ACTIVE` - `context_ctrl`: - Bit 0: right control active, checked with macro `SH_KBD_EVENT_RIGHT_ACTIVE` - Bit 1: left control active, checked with macro `SH_KBD_EVENT_LEFT_ACTIVE` - `context_lock_status`: - Bit 0: numlock active, checked with `SH_KBD_EVENT_NUMLOCK_ACTIVE` - Bit 0: capslock active, checked with `SH_KBD_EVENT_CAPSLOCK_ACTIVE` There is a precise way of interpreting what this structure mean. It start by checking the value of `event_type`. ### `SH_EVENT_TYPE_KBD_PAUSE` The event is a press of the pause key. The `scancode` and `pressed` fields should be ignored. ### `SH_EVENT_TYPE_KBD_CONTEXT` This event is a press of a modifier key. It allows to abstract modifiers keys events accross all types of keyboards. The scancode must be one of the following: - `SH_KBD_CONTEXT_LSHIFT` - `SH_KBD_CONTEXT_RSHIFT` - `SH_KBD_CONTEXT_LCTRL` - `SH_KBD_CONTEXT_RCTRL` - `SH_KBD_CONTEXT_LALT` - `SH_KBD_CONTEXT_RALT` - `SH_KBD_CONTEXT_WIN` - `SH_KBD_CONTEXT_NUMLOCK` - `SH_KBD_CONTEXT_CAPSLOCK` You need to check the `pressed` boolean to know if the key was pressed or released. ### `SH_EVENT_TYPE_PS2_NORMAL` This event type represents a standard PS2 Set1 scancode. The scancode is put in the low 8 bits of the `scancode` fields. The high 8 bits are set to 0. You need to check the `pressed` boolean to know if the key was pressed or released. ### `SH_EVENT_TYPE_PS2_E0` This event type represents an extended PS2 Set1 scancode prefixed by `0xE0`. The scancode is put in the low 8 bits of the `scancode` fields. The high 8 bits are set to `0xE0`. You need to check the `pressed` boolean to know if the key was pressed or released. ### Notes For `SH_EVENT_TYPE_PS2_NORMAL` and `SH_EVENT_TYPE_PS2_E0` events type, the scancode, when `pressed` is `SH_FALSE`, keeps its bit 8 to 1.