Changeset 7309799 in mainline

Timestamp:

2011-03-10T14:13:15Z (13 years ago)

Author:

Lubos Slovak <lubos.slovak@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

e8c1fb0

Parents:

17ada7a

Message:

Comments of kbdrepeat functions + minor changes to comments in kbddev.

Location:

uspace/drv/usbhid

Files:

• kbddev.c (modified) (1 diff)
• kbdrepeat.c (modified) (4 diffs)

uspace/drv/usbhid/kbddev.c

@@ -484 +484 @@
  * @param count Number of key codes in report (size of the report).
  * @param modifiers Bitmap of modifiers (Ctrl, Alt, Shift, GUI).
- * @param arg User-specified argument.
+ * @param arg User-specified argument. Expects pointer to the keyboard device
+ *            structure representing the keyboard.
  *
  * @sa usbhid_kbd_check_key_changes(), usbhid_kbd_check_modifier_changes()

uspace/drv/usbhid/kbdrepeat.c

@@ -45 +45 @@
 #include "kbddev.h"
 
+
+/** Delay between auto-repeat state checks when no key is being repeated. */
 static unsigned int CHECK_DELAY = 10000;
 
 /*----------------------------------------------------------------------------*/
-
+/**
+ * Main loop handling the auto-repeat of keys.
+ *
+ * This functions periodically checks if there is some key to be auto-repeated.
+ *
+ * If a new key is to be repeated, it uses the delay before first repeat stored
+ * in the keyboard structure to wait until the key has to start repeating.
+ *
+ * If the same key is still pressed, it uses the delay between repeats stored
+ * in the keyboard structure to wait until the key should be repeated.
+ * 
+ * If the currently repeated key is not pressed any more (
+ * usbhid_kbd_repeat_stop() was called), it stops repeating it and starts 
+ * checking again.
+ *
+ * @note For accessing the keyboard device auto-repeat information a fibril
+ *       mutex (repeat_mtx) from the @a kbd structure is used.
+ * 
+ * @param kbd Keyboard device structure.
+ */
 static void usbhid_kbd_repeat_loop(usbhid_kbd_t *kbd)
 {
@@ -86 +107 @@
 
 /*----------------------------------------------------------------------------*/
-
+/**
+ * Main routine to be executed by a fibril for handling auto-repeat.
+ *
+ * Starts the loop for checking changes in auto-repeat.
+ * 
+ * @param arg User-specified argument. Expects pointer to the keyboard device
+ *            structure representing the keyboard.
+ *
+ * @retval EOK if the routine has finished.
+ * @retval EINVAL if no argument is supplied.
+ */
 int usbhid_kbd_repeat_fibril(void *arg)
 {
@@ -104 +135 @@
 
 /*----------------------------------------------------------------------------*/
-
+/**
+ * Start repeating particular key.
+ *
+ * @note Only one key is repeated at any time, so calling this function 
+ *       effectively cancels auto-repeat of the current repeated key (if any)
+ *       and 'schedules' another key for auto-repeat.
+ *
+ * @param kbd Keyboard device structure.
+ * @param key Key to start repeating.
+ */
 void usbhid_kbd_repeat_start(usbhid_kbd_t *kbd, unsigned int key)
 {
@@ -113 +153 @@
 
 /*----------------------------------------------------------------------------*/
-
+/**
+ * Stop repeating particular key.
+ *
+ * @note Only one key is repeated at any time, but this function may be called
+ *       even with key that is not currently repeated (in that case nothing 
+ *       happens).
+ *
+ * @param kbd Keyboard device structure.
+ * @param key Key to stop repeating.
+ */
 void usbhid_kbd_repeat_stop(usbhid_kbd_t *kbd, unsigned int key)
 {