forked from lolo859/vystem
Vystem 0.2
This commit is contained in:
134
docs/shelter/devs/kbdinput.md
Normal file
134
docs/shelter/devs/kbdinput.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user