Changeset 48d2765 in mainline


Ignore:
Timestamp:
2011-03-08T21:42:51Z (14 years ago)
Author:
Lubos Slovak <lubos.slovak@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
269bd9b4
Parents:
d2fc1c2
Message:

Doxygen comments, part 1

Location:
uspace/drv/usbhid
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • uspace/drv/usbhid/kbddev.c

    rd2fc1c2 r48d2765  
    196196        unsigned mod_mask;
    197197
    198         // TODO: replace by our own parsing?? or are the key codes identical??
     198        /*
     199         * These parts are copy-pasted from the AT keyboard driver.
     200         *
     201         * They definitely require some refactoring, but will keep it for later
     202         * when the console and keyboard system is changed in HelenOS.
     203         */
    199204        switch (key) {
    200205        case KC_LCTRL: mod_mask = KM_LCTRL; break;
    … …  
    328333        i = 0;
    329334        // all fields should report Error Rollover
    330         while (i < kbd_dev->keycode_count &&
     335        while (i < kbd_dev->key_count &&
    331336            key_codes[i] == BOOTP_ERROR_ROLLOVER) {
    332337                ++i;
    333338        }
    334         if (i == kbd_dev->keycode_count) {
     339        if (i == kbd_dev->key_count) {
    335340                usb_log_debug("Phantom state occured.\n");
    336341                // phantom state, do nothing
    … …  
    343348         * 1) Key releases
    344349         */
    345         for (j = 0; j < kbd_dev->keycode_count; ++j) {
     350        for (j = 0; j < kbd_dev->key_count; ++j) {
    346351                // try to find the old key in the new key list
    347352                i = 0;
    348                 while (i < kbd_dev->keycode_count
    349                     && key_codes[i] != kbd_dev->keycodes[j]) {
     353                while (i < kbd_dev->key_count
     354                    && key_codes[i] != kbd_dev->keys[j]) {
    350355                        ++i;
    351356                }
    352357               
    353                 if (i == kbd_dev->keycode_count) {
     358                if (i == kbd_dev->key_count) {
    354359                        // not found, i.e. the key was released
    355                         key = usbhid_parse_scancode(kbd_dev->keycodes[j]);
     360                        key = usbhid_parse_scancode(kbd_dev->keys[j]);
    356361                        usbhid_kbd_push_ev(kbd_dev, KEY_RELEASE, key);
    357362                        usb_log_debug2("Key released: %d\n", key);
    … …  
    364369         * 1) Key presses
    365370         */
    366         for (i = 0; i < kbd_dev->keycode_count; ++i) {
     371        for (i = 0; i < kbd_dev->key_count; ++i) {
    367372                // try to find the new key in the old key list
    368373                j = 0;
    369                 while (j < kbd_dev->keycode_count
    370                     && kbd_dev->keycodes[j] != key_codes[i]) {
     374                while (j < kbd_dev->key_count
     375                    && kbd_dev->keys[j] != key_codes[i]) {
    371376                        ++j;
    372377                }
    373378               
    374                 if (j == kbd_dev->keycode_count) {
     379                if (j == kbd_dev->key_count) {
    375380                        // not found, i.e. new key pressed
    376381                        key = usbhid_parse_scancode(key_codes[i]);
    … …  
    392397//      }
    393398       
    394         memcpy(kbd_dev->keycodes, key_codes, kbd_dev->keycode_count);
     399        memcpy(kbd_dev->keys, key_codes, kbd_dev->key_count);
    395400
    396401        usb_log_debug("New stored keycodes: %s\n",
    397             usb_debug_str_buffer(kbd_dev->keycodes, kbd_dev->keycode_count, 0));
     402            usb_debug_str_buffer(kbd_dev->keys, kbd_dev->key_count, 0));
    398403}
    399404
    … …  
    415420
    416421        usb_log_debug("Got keys from parser: %s\n",
    417             usb_debug_str_buffer(key_codes, kbd_dev->keycode_count, 0));
    418        
    419         if (count != kbd_dev->keycode_count) {
     422            usb_debug_str_buffer(key_codes, kbd_dev->key_count, 0));
     423       
     424        if (count != kbd_dev->key_count) {
    420425                usb_log_warning("Number of received keycodes (%d) differs from"
    421                     " expected number (%d).\n", count, kbd_dev->keycode_count);
     426                    " expected number (%d).\n", count, kbd_dev->key_count);
    422427                return;
    423428        }
    … …  
    430435/* General kbd functions                                                      */
    431436/*----------------------------------------------------------------------------*/
    432 
     437/**
     438 * Processes data received from the device in form of report.
     439 *
     440 * This function uses the HID report parser to translate the data received from
     441 * the device into generic USB HID key codes and into generic modifiers bitmap.
     442 * The parser then calls the given callback (usbhid_kbd_process_keycodes()).
     443 *
     444 * @note Currently, only the boot protocol is supported.
     445 *
     446 * @param kbd_dev Keyboard device structure (must be initialized).
     447 * @param buffer Data from the keyboard (i.e. the report).
     448 * @param actual_size Size of the data from keyboard (report size) in bytes.
     449 *
     450 * @sa usbhid_kbd_process_keycodes(), usb_hid_boot_keyboard_input_report().
     451 */
    433452static void usbhid_kbd_process_data(usbhid_kbd_t *kbd_dev,
    434453                                    uint8_t *buffer, size_t actual_size)
    … …  
    455474/* HID/KBD structure manipulation                                             */
    456475/*----------------------------------------------------------------------------*/
    457 
     476/**
     477 * Creates a new USB/HID keyboard structure.
     478 *
     479 * The structure returned by this function is not initialized. Use
     480 * usbhid_kbd_init() to initialize it prior to polling.
     481 *
     482 * @return New uninitialized structure for representing a USB/HID keyboard or
     483 *         NULL if not successful (memory error).
     484 */
    458485static usbhid_kbd_t *usbhid_kbd_new(void)
    459486{
    … …  
    481508
    482509/*----------------------------------------------------------------------------*/
    483 
     510/**
     511 * Properly destroys the USB/HID keyboard structure.
     512 *
     513 * @param kbd_dev Pointer to the structure to be destroyed.
     514 */
    484515static void usbhid_kbd_free(usbhid_kbd_t **kbd_dev)
    485516{
    … …  
    501532
    502533/*----------------------------------------------------------------------------*/
    503 
     534/**
     535 * Initialization of the USB/HID keyboard structure.
     536 *
     537 * This functions initializes required structures from the device's descriptors.
     538 *
     539 * During initialization, the keyboard is switched into boot protocol, the idle
     540 * rate is set to 0 (infinity), resulting in the keyboard only reporting event
     541 * when a key is pressed or released. Finally, the LED lights are turned on
     542 * according to the default setup of lock keys.
     543 *
     544 * @note By default, the keyboards is initialized with Num Lock turned on and
     545 *       other locks turned off.
     546 *
     547 * @param kbd_dev Keyboard device structure to be initialized.
     548 * @param dev DDF device structure of the keyboard.
     549 *
     550 * @retval EOK if successful.
     551 * @retval EINVAL if some parameter is not given.
     552 * @return Other value inherited from function usbhid_dev_init().
     553 */
    504554static int usbhid_kbd_init(usbhid_kbd_t *kbd_dev, ddf_dev_t *dev)
    505555{
    … …  
    536586       
    537587        // save the size of the report (boot protocol report by default)
    538         kbd_dev->keycode_count = BOOTP_REPORT_SIZE;
    539         kbd_dev->keycodes = (uint8_t *)calloc(
    540             kbd_dev->keycode_count, sizeof(uint8_t));
    541        
    542         if (kbd_dev->keycodes == NULL) {
     588        kbd_dev->key_count = BOOTP_REPORT_SIZE;
     589        kbd_dev->keys = (uint8_t *)calloc(
     590            kbd_dev->key_count, sizeof(uint8_t));
     591       
     592        if (kbd_dev->keys == NULL) {
    543593                usb_log_fatal("No memory!\n");
    544                 return rc;
     594                return ENOMEM;
    545595        }
    546596       
    … …  
    571621/* HID/KBD polling                                                            */
    572622/*----------------------------------------------------------------------------*/
    573 
     623/**
     624 * Main keyboard polling function.
     625 *
     626 * This function uses the Interrupt In pipe of the keyboard to poll for events.
     627 * The keyboard is initialized in a way that it reports only when a key is
     628 * pressed or released, so there is no actual need for any sleeping between
     629 * polls (see usbhid_kbd_try_add_device() or usbhid_kbd_init()).
     630 *
     631 * @param kbd_dev Initialized keyboard structure representing the device to
     632 *                poll.
     633 *
     634 * @sa usbhid_kbd_process_data()
     635 */
    574636static void usbhid_kbd_poll(usbhid_kbd_t *kbd_dev)
    575637{
    … …  
    639701
    640702/*----------------------------------------------------------------------------*/
    641 
     703/**
     704 * Function executed by the main driver fibril.
     705 *
     706 * Just starts polling the keyboard for events.
     707 *
     708 * @param arg Initialized keyboard device structure (of type usbhid_kbd_t)
     709 *            representing the device.
     710 *
     711 * @retval EOK if the fibril finished polling the device.
     712 * @retval EINVAL if no device was given in the argument.
     713 *
     714 * @sa usbhid_kbd_poll()
     715 *
     716 * @todo Change return value - only case when the fibril finishes is in case
     717 *       of some error, so the error should probably be propagated from function
     718 *       usbhid_kbd_poll() to here and up.
     719 */
    642720static int usbhid_kbd_fibril(void *arg)
    643721{
    … …  
    661739/* API functions                                                              */
    662740/*----------------------------------------------------------------------------*/
    663 
     741/**
     742 * Function for adding a new device of type USB/HID/keyboard.
     743 *
     744 * This functions initializes required structures from the device's descriptors
     745 * and starts a new fibril for polling the keyboard for events.
     746 *
     747 * During initialization, the keyboard is switched into boot protocol, the idle
     748 * rate is set to 0 (infinity), resulting in the keyboard only reporting event
     749 * when a key is pressed or released. Finally, the LED lights are turned on
     750 * according to the default setup of lock keys.
     751 *
     752 * @note By default, the keyboards is initialized with Num Lock turned on and
     753 *       other locks turned off.
     754 * @note Currently supports only boot-protocol keyboards.
     755 *
     756 * @param dev Device to add.
     757 *
     758 * @retval EOK if successful.
     759 * @retval ENOMEM if there
     760 * @return Other error code inherited from one of functions usbhid_kbd_init(),
     761 *         ddf_fun_bind() and ddf_fun_add_to_class().
     762 *
     763 * @sa usbhid_kbd_fibril()
     764 */
    664765int usbhid_kbd_try_add_device(ddf_dev_t *dev)
    665766{
    … …  
    683784                    "structure.\n");
    684785                ddf_fun_destroy(kbd_fun);
    685                 return EINVAL;  // TODO: some other code??
     786                return ENOMEM;  // TODO: some other code??
    686787        }
    687788       

  • uspace/drv/usbhid/kbddev.h

    rd2fc1c2 r48d2765  
    4646
    4747/*----------------------------------------------------------------------------*/
    48 
    4948/**
    50  * @brief USB/HID keyboard device type.
     49 * USB/HID keyboard device type.
     50 *
     51 * Holds a reference to generic USB/HID device structure and keyboard-specific
     52 * data, such as currently pressed keys, modifiers and lock keys.
     53 *
     54 * Also holds a IPC phone to the console (since there is now no other way to
     55 * communicate with it).
     56 *
     57 * @note Storing active lock keys in this structure results in their setting
     58 *       being device-specific.
    5159 */
    5260typedef struct {
     61        /** Structure holding generic USB/HID device information. */
    5362        usbhid_dev_t *hid_dev;
    5463       
    55         uint8_t *keycodes;
    56         size_t keycode_count;
     64        /** Currently pressed keys (not translated to key codes). */
     65        uint8_t *keys;
     66        /** Count of stored keys (i.e. number of keys in the report). */
     67        size_t key_count;
     68        /** Currently pressed modifiers (bitmap). */
    5769        uint8_t modifiers;
    5870       
     71        /** Currently active modifiers including locks. Sent to the console. */
    5972        unsigned mods;
     73       
     74        /** Currently active lock keys. */
    6075        unsigned lock_keys;
    6176       
     77        /** IPC phone to the console device (for sending key events). */
    6278        int console_phone;
    6379       
     80        /** State of the structure (for checking before use). */
    6481        int initialized;
    6582} usbhid_kbd_t;

  • uspace/drv/usbhid/main.c

    rd2fc1c2 r48d2765  
    4747
    4848/*----------------------------------------------------------------------------*/
    49 
     49/**
     50 * Callback for passing a new device to the driver.
     51 *
     52 * @note Currently, only boot-protocol keyboards are supported by this driver.
     53 *
     54 * @param dev Structure representing the new device.
     55 *
     56 * @retval EOK if successful.
     57 * @retval EREFUSED if the device is not supported.
     58 */
    5059static int usbhid_add_device(ddf_dev_t *dev)
    5160{
Note: See TracChangeset for help on using the changeset viewer.