From: John Hodge Date: Thu, 1 Mar 2012 13:01:41 +0000 (+0800) Subject: Modules/Keyboard - Improving documentation X-Git-Tag: rel0.15~741 X-Git-Url: https://git.ucc.asn.au/?a=commitdiff_plain;h=66cb73e82a05896035f605c96fde8b8a68e07bb9;p=tpg%2Facess2.git Modules/Keyboard - Improving documentation --- diff --git a/KernelLand/Modules/Input/Keyboard/include/keyboard.h b/KernelLand/Modules/Input/Keyboard/include/keyboard.h index c5753998..d8a14f65 100644 --- a/KernelLand/Modules/Input/Keyboard/include/keyboard.h +++ b/KernelLand/Modules/Input/Keyboard/include/keyboard.h @@ -10,11 +10,39 @@ #include +/** + * \brief Keyboard instance + * + * Used to refer to a keyboard state (current key states, keymap and destination + * node) + */ typedef struct sKeyboard tKeyboard; +/** + * \brief Create a keyboard instance + * \param MaxSym Maximum key symbol that could be passed to Keyboard_HandleKey + * \param Ident Identifier for this keyboard (e.g. "PS2Keyboard") + * \return Keyboard instance pointer + * + * The \a MaxSym parameter is used to create a bitmap of key states + */ extern tKeyboard *Keyboard_CreateInstance(int MaxSym, const char *Ident); +/** + * \brief De-register and free a keyboard instance + * \param Instance Value returned by Keyboard_CreateInstance + */ extern void Keyboard_RemoveInstance(tKeyboard *Instance); -extern void Keyboard_HandleKey(tKeyboard *Source, Uint32 HIDKeySym); +/** + * \brief Handle a key press/release event from the driver + * \param Instance Keyboard instance returned by Keyboard_CreateInstance + * \param HIDKeySym USB HID Key symbol (KEYSYM_* in Kernel/include/keysym.h), bit 31 denotes release + * + * The value in \a HIDKeySym is a USB HID key symbol, but this could come from anywhere. + * The topmost bit of the 32-bit value is used to denote the key being released, if it is set + * the key state is cleared and a release event is passed along. Otherwise it is set, + * and a refire or a press event is passed (depending on the original key state) + */ +extern void Keyboard_HandleKey(tKeyboard *Instance, Uint32 HIDKeySym); #endif diff --git a/KernelLand/Modules/Input/Keyboard/main.c b/KernelLand/Modules/Input/Keyboard/main.c index 17c0f5fc..ccec8f5c 100644 --- a/KernelLand/Modules/Input/Keyboard/main.c +++ b/KernelLand/Modules/Input/Keyboard/main.c @@ -1,9 +1,9 @@ /* - * Acess2 Kernel - Keyboard Character Mappings + * Acess2 Kernel - Keyboard Driver * - By John Hodge (thePowersGang) * * main.c - * - Core keyboard multiplexer + * - Keyboard driver core * * TODO: Make the key transation code more general (for non-US layouts) * TODO: Support multiple virtual keyboards @@ -54,28 +54,49 @@ tDevFS_Driver gKB_DevInfo = { #endif // === CODE === +/** + * \brief Initialise the keyboard driver + */ int Keyboard_Install(char **Arguments) { + /// - Register with DevFS DevFS_AddDevice( &gKB_DevInfo ); return 0; } +/** + * \brief Pre-unload cleanup function + */ void Keyboard_Cleanup(void) { // TODO: Do I need this? } -tKeymap *Keyboard_LoadMap(const char *Name) +// --- Map Management --- +/** + * \brief Load an arbitary keyboard map + * \param Name Keymap name (e.g. "en-us") + * \return Keymap pointer + */ +tKeymap *Keyboard_int_LoadMap(const char *Name) { + Log_Warning("Keyboard", "TOD: Impliment Keyboard_int_LoadMap"); return NULL; } -void Keyboard_FreeMap(tKeymap *Keymap) +/** + * \brief Unload a keyboard map + * \param Keymap Keymap to unload/free + */ +void Keyboard_int_FreeMap(tKeymap *Keymap) { } // --- VFS Interface --- static const char *csaIOCTL_NAMES[] = {DRV_IOCTLNAMES, DRV_KEYBAORD_IOCTLNAMES, NULL}; +/** + * \brief Keyboard IOCtl + */ int Keyboard_IOCtl(tVFS_Node *Node, int Id, void *Data) { switch(Id) @@ -93,6 +114,11 @@ int Keyboard_IOCtl(tVFS_Node *Node, int Id, void *Data) } // --- Device Interface --- +/* + * Create a new keyboard device instance + * TODO: Allow linking to other VFS nodes + * See Input/Keyboard/include/keyboard.h + */ tKeyboard *Keyboard_CreateInstance(int MaxSym, const char *Name) { tKeyboard *ret; @@ -115,12 +141,20 @@ tKeyboard *Keyboard_CreateInstance(int MaxSym, const char *Name) return ret; } +/* + * Destroy a keyboard instance + * - See Input/Keyboard/include/keyboard.h + */ void Keyboard_RemoveInstance(tKeyboard *Instance) { // TODO: Implement Log_Error("Keyboard", "TODO: Implement Keyboard_RemoveInstance"); } +/* + * Handle a key press/release event + * - See Input/Keyboard/include/keyboard.h + */ void Keyboard_HandleKey(tKeyboard *Source, Uint32 HIDKeySym) { int bPressed; @@ -131,7 +165,7 @@ void Keyboard_HandleKey(tKeyboard *Source, Uint32 HIDKeySym) bPressed = !(HIDKeySym & (1 << 31)); HIDKeySym &= 0x7FFFFFFF; - // Determine action + // - Determine the action (Press, Release or Refire) { Uint8 mask = 1 << (HIDKeySym&7); int ofs = HIDKeySym / 8; @@ -152,7 +186,7 @@ void Keyboard_HandleKey(tKeyboard *Source, Uint32 HIDKeySym) else Source->KeyStates[ ofs ] &= ~mask; - // Get the action (Press, Refire or Release) + // Get the final flag if( bPressed ) { if( !oldstate && !otherstate ) @@ -165,7 +199,7 @@ void Keyboard_HandleKey(tKeyboard *Source, Uint32 HIDKeySym) if( !otherstate ) flag = KEY_ACTION_RELEASE; // Up else - flag = -1 ; // Do nothing + flag = -1; // Do nothing } } @@ -173,7 +207,7 @@ void Keyboard_HandleKey(tKeyboard *Source, Uint32 HIDKeySym) // TODO: Support non-trivial layouts layer = !!(Source->State & 3); - // Send raw symbol + // Do translation if( flag == KEY_ACTION_RELEASE ) trans = 0; else { @@ -190,6 +224,7 @@ void Keyboard_HandleKey(tKeyboard *Source, Uint32 HIDKeySym) trans = Source->Keymap->Layers[0]->Sym[HIDKeySym]; } + // Call callback (only if the action is valid) if( flag != -1 ) { tKeybardCallback Callback = (void*)Source->Node->ImplInt; @@ -212,7 +247,8 @@ void Keyboard_HandleKey(tKeyboard *Source, Uint32 HIDKeySym) // --- Check for Kernel Magic Combos #if USE_KERNEL_MAGIC - if(Source->KeyStates[KEYSYM_LEFTCTRL/8] & (1 << (KEYSYM_LEFTCTRL&7)) + if(bPressed + && Source->KeyStates[KEYSYM_LEFTCTRL/8] & (1 << (KEYSYM_LEFTCTRL&7)) && Source->KeyStates[KEYSYM_LEFTALT/8] & (1 << (KEYSYM_LEFTALT &7)) ) { int val;