X-Git-Url: https://git.ucc.asn.au/?a=blobdiff_plain;f=Kernel%2Finclude%2Ftpl_drv_keyboard.h;h=8f4c1585598418e1b60c82f255b31ee48d254e30;hb=de2ae10743172075f2d527780bdfd890ccddb8e7;hp=9d3e5dcaa40affe2e84e77a34e7d1ad3322e2e67;hpb=8bc40333b1401d7616b225945fee53d972c2f418;p=tpg%2Facess2.git

diff --git a/Kernel/include/tpl_drv_keyboard.h b/Kernel/include/tpl_drv_keyboard.h
index 9d3e5dca..8f4c1585 100644
--- a/Kernel/include/tpl_drv_keyboard.h
+++ b/Kernel/include/tpl_drv_keyboard.h
@@ -1,7 +1,13 @@
 /**
  * \file tpl_drv_keyboard.h
  * \brief Keyboard Driver Interface Definitions
-*/
+ * \author John Hodge (thePowersGang)
+ * 
+ * \section dirs VFS Layout
+ * Keyboard drivers consist of only a single node, which is a normal file
+ * node with a size of zero. All reads and writes to this node are ignored
+ * (tVFS_Node.Read and tVFS_Node.Write are NULL)
+ */
 #ifndef _TPL_KEYBOARD_H
 #define _TPL_KEYBOARD_H
 
@@ -13,23 +19,69 @@
  * \extends eTplDrv_IOCtl
  */
 enum eTplKeyboard_IOCtl {
-	//! \brief Get/Set Repeat Rate - (int Rate)
+	/**
+	 * ioctl(..., int *Rate)
+	 * \brief Get/Set Repeat Rate
+	 * \param Rate	New repeat rate (pointer)
+	 * \return Current/New Repeat rate
+	 * 
+	 * Gets/Set the repeat rate (actually the time in miliseconds between
+	 * repeats) of a held down key.
+	 * If the rate is set to zero, repeating will be disabled.
+	 */
 	KB_IOCTL_REPEATRATE = 4,
-	//! \brief Get/Set Repeat Delay - (int Delay)
+	
+	/**
+	 * ioctl(..., int *Delay)
+	 * \brief Get/Set Repeat Delay
+	 * \param Delay	New repeat delay (pointer)
+	 * \return Current/New repeat delay
+	 * 
+	 * Gets/Set the time in miliseconds before a key starts repeating
+	 * after a key is pressed.
+	 * Setting the delay to a negative number will cause the function to
+	 * return -1
+	 */
 	KB_IOCTL_REPEATDELAY,
-	//! \brief Sets the callback
+	
+	
+	/**
+	 * ioctl(..., tKeybardCallback *Callback)
+	 * \brief Sets the callback
+	 * \note Can be called from kernel mode only
+	 * 
+	 * Sets the function to be called when a key event occurs (press, release
+	 * or repeat). This function pointer must be in kernel mode (although,
+	 * kernel->user or kernel->ring3driver abstraction functions can be used)
+	 */
 	KB_IOCTL_SETCALLBACK
 };
 
-typedef void (*tKeybardCallback)(Uint32);
+/**
+ * \brief Callback type for KB_IOCTL_SETCALLBACK
+ * \param Key Unicode character code for the pressed key (with bit 31
+ *            set if the key is released)
+ */
+typedef void (*tKeybardCallback)(Uint32 Key);
 
-enum {
-	KEY_ESC = 0x1B,
+/**
+ * \brief Symbolic key codes
+ * 
+ * These key codes represent non-pritable characters and are placed above
+ * the Unicode character space.
+ * If the using driver recieves a key code with the 31st bit set, it means
+ * that that key has been released.
+ */
+enum eTplKeyboard_KeyCodes {
+	KEY_ESC = 0x1B,	//!< Escape Character
 	
-	KEY_NP_MASK = 0x80,	//End of ASCII Range
-	KEY_LCTRL, KEY_RCTRL,
-	KEY_LALT, KEY_RALT,
-	KEY_LSHIFT, KEY_RSHIFT,
+	KEY_NP_MASK = 0x40000000,	//! Mask for non-printable characters
+	
+	/**
+	 * \name Special Keys
+	 * \brief These keys are usually used on their own
+	 * \{
+	 */
 	KEY_CAPSLOCK,
 	KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT,
 	KEY_F1, KEY_F2, KEY_F3, KEY_F4, KEY_F5, KEY_F6, 
@@ -42,8 +94,23 @@ enum {
 	KEY_KPHOME, KEY_KPUP, KEY_KPPGUP, KEY_KPLEFT, KEY_KP5, KEY_KPRIGHT,
 	KEY_KPEND, KEY_KPDOWN, KEY_KPPGDN, KEY_KPINS, KEY_KPDEL,
 	KEY_WIN, KEY_MENU,
+	/**
+	 * \}
+	 */
 	
-	KEY_KEYUP = 0xFF
+	// Modifiers
+	/**
+	 * \name Modifiers
+	 * \brief These keye usually alter the character stream sent to the user
+	 * \{
+	 */
+	KEY_MODIFIERS = 0x60000000,
+	KEY_LCTRL, KEY_RCTRL,
+	KEY_LALT, KEY_RALT,
+	KEY_LSHIFT, KEY_RSHIFT,
+	/**
+	 * \}
+	 */
 };