Ignore:
Timestamp:
2011-05-20T12:49:13Z (13 years ago)
Author:
Matej Klonfar <maklf@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
5499a8b, c9256c5
Parents:
7941bd6
Message:

hid parser header's doxygen doc

File:
1 edited

Legend:

Unmodified
Added
Removed
  • uspace/lib/usbhid/include/usb/hid/hidtypes.h

    r7941bd6 r74b1e40  
    2727 */
    2828
    29 /** @addtogroup libusbhid
     29/** @addtogroup libusb
    3030 * @{
    3131 */
    3232/** @file
    33  * USB HID report descriptor and report data parser
    34  */
    35 #ifndef LIBUSBHID_HIDTYPES_H_
    36 #define LIBUSBHID_HIDTYPES_H_
     33 * Basic data structures for USB HID Report descriptor and report parser.
     34 */
     35#ifndef LIBUSB_HIDTYPES_H_
     36#define LIBUSB_HIDTYPES_H_
    3737
    3838#include <stdint.h>
    3939#include <adt/list.h>
    4040
     41/*---------------------------------------------------------------------------*/
     42
     43/**
     44 * Maximum amount of specified usages for one report item
     45 */
    4146#define USB_HID_MAX_USAGES      0xffff
    4247
    43 #define USB_HID_UINT32_TO_INT32(x, size)        ((((x) & (1 << ((size) - 1))) != 0) ? -(~(x - 1) & ((1 << size) - 1)) : (x)) //(-(~((x) - 1)))
    44 #define USB_HID_INT32_TO_UINT32(x, size)        (((x) < 0 ) ? ((1 << (size)) + (x)) : (x))
    45 
    46 
     48/**
     49 * Converts integer from unsigned two's complement format format to signed
     50 * one.
     51 *
     52 * @param x Number to convert
     53 * @param size Length of the unsigned number in bites
     54 * @return signed int
     55 */
     56#define USB_HID_UINT32_TO_INT32(x, size)        \
     57        ((((x) & (1 << ((size) - 1))) != 0) ?   \
     58         -(~((x) - 1) & ((1 << size) - 1)) : (x))
     59
     60/**
     61 * Convert integer from signed format to unsigned. If number is negative the
     62 * two's complement format is used.
     63 *
     64 * @param x Number to convert
     65 * @param size Length of result number in bites
     66 * @return unsigned int
     67 */
     68#define USB_HID_INT32_TO_UINT32(x, size)        \
     69        (((x) < 0 ) ? ((1 << (size)) + (x)) : (x))
     70
     71/*---------------------------------------------------------------------------*/
     72
     73/**
     74 * Report type
     75 */
    4776typedef enum {
    4877        USB_HID_REPORT_TYPE_INPUT = 1,
     
    5180} usb_hid_report_type_t;
    5281
    53 
     82/*---------------------------------------------------------------------------*/
     83
     84/**
     85 * Description of all reports described in one report descriptor.
     86 */
    5487typedef struct {
    55         /** */
     88        /** Count of available reports. */
    5689        int report_count;
    57         link_t reports;         /** list of usb_hid_report_description_t */
    58 
     90
     91        /** Head of linked list of description of reports. */
     92        link_t reports;
     93
     94        /** Head of linked list of all used usage/collection paths. */
    5995        link_t collection_paths;
     96
     97        /** Length of list of usage paths. */
    6098        int collection_paths_count;
    6199
     100        /** Flag whether report ids are used. */
    62101        int use_report_ids;
     102
     103        /** Report id of last parsed report. */
    63104        uint8_t last_report_id;
    64105       
    65106} usb_hid_report_t;
    66 
     107/*---------------------------------------------------------------------------*/
     108
     109/**
     110 * Description of one concrete report
     111 */
    67112typedef struct {
     113        /** Report id. Zero when no report id is used. */
    68114        uint8_t report_id;
     115
     116        /** Type of report */
    69117        usb_hid_report_type_t type;
    70118
     119        /** Bit length of the report */
    71120        size_t bit_length;
     121
     122        /** Number of items in report */
    72123        size_t item_length;
    73124       
    74         link_t report_items;    /** list of report items (fields) */
    75 
     125        /** Linked list of report items in report */
     126        link_t report_items;
     127
     128        /** Linked list of descriptions. */
    76129        link_t link;
    77130} usb_hid_report_description_t;
    78 
     131/*---------------------------------------------------------------------------*/
     132
     133/**
     134 * Description of one field/item in report
     135 */
    79136typedef struct {
    80 
     137        /** Bit offset of the field */
    81138        int offset;
     139
     140        /** Bit size of the field */
    82141        size_t size;
    83142
     143        /** Usage page. Zero when usage page can be changed. */
    84144        uint16_t usage_page;
     145
     146        /** Usage. Zero when usage can be changed. */
    85147        uint16_t usage;
    86148
     149        /** Item's attributes */
    87150        uint8_t item_flags;
     151
     152        /** Usage/Collection path of the field. */
    88153        usb_hid_report_path_t *collection_path;
    89154
     155        /**
     156         * The lowest valid logical value (value with the device operates)
     157         */
    90158        int32_t logical_minimum;
     159
     160        /**
     161         * The greatest valid logical value
     162         */
    91163        int32_t logical_maximum;
     164
     165        /**
     166         * The lowest valid physical value (value with the system operates)
     167         */
    92168        int32_t physical_minimum;
     169
     170        /** The greatest valid physical value */
    93171        int32_t physical_maximum;
     172
     173        /** The lowest valid usage index */
    94174        int32_t usage_minimum;
     175
     176        /** The greatest valid usage index */
    95177        int32_t usage_maximum;
     178       
     179        /** Unit of the value */
    96180        uint32_t unit;
     181
     182        /** Unit exponent */
    97183        uint32_t unit_exponent;
    98184
     185        /** Array of possible usages */
    99186        uint32_t *usages;
     187
     188        /** Size of the array of usages */
    100189        size_t usages_count;
    101190
     191        /** Parsed value */
    102192        int32_t value;
    103193
     194        /** List to another report items */
    104195        link_t link;
    105196} usb_hid_report_field_t;
    106197
    107 
    108 
    109 /**
    110  * state table
     198/*---------------------------------------------------------------------------*/
     199
     200/**
     201 * State table for report descriptor parsing
    111202 */
    112203typedef struct {
     
    114205        int32_t id;
    115206       
    116         /** */
     207        /** Extended usage page */
    117208        uint16_t extended_usage_page;
     209
     210        /** Array of usages specified for this item */
    118211        uint32_t usages[USB_HID_MAX_USAGES];
     212       
     213        /** Length of usages array */
    119214        int usages_count;
    120215
    121         /** */
     216        /** Usage page*/
    122217        uint32_t usage_page;
    123218
    124         /** */ 
     219        /** Minimum valid usage index */       
    125220        int32_t usage_minimum;
    126         /** */ 
     221       
     222        /** Maximum valid usage index */       
    127223        int32_t usage_maximum;
    128         /** */ 
     224       
     225        /** Minimum valid logical value */     
    129226        int32_t logical_minimum;
    130         /** */ 
     227       
     228        /** Maximum valid logical value */     
    131229        int32_t logical_maximum;
    132         /** */ 
     230
     231        /** Length of the items in bits*/       
    133232        int32_t size;
    134         /** */ 
     233
     234        /** COunt of items*/   
    135235        int32_t count;
    136         /** */ 
     236
     237        /**  Bit offset of the item in report */       
    137238        size_t offset;
    138         /** */ 
     239
     240        /** Unit exponent */   
    139241        int32_t unit_exponent;
    140         /** */ 
     242        /** Unit of the value */       
    141243        int32_t unit;
    142244
    143         /** */
     245        /** String index */
    144246        uint32_t string_index;
    145         /** */ 
     247
     248        /** Minimum valid string index */       
    146249        uint32_t string_minimum;
    147         /** */ 
     250
     251        /** Maximum valid string index */       
    148252        uint32_t string_maximum;
    149         /** */ 
     253
     254        /** The designator index */     
    150255        uint32_t designator_index;
    151         /** */ 
     256
     257        /** Minimum valid designator value*/   
    152258        uint32_t designator_minimum;
    153         /** */ 
     259
     260        /** Maximum valid designator value*/   
    154261        uint32_t designator_maximum;
    155         /** */ 
     262
     263        /** Minimal valid physical value*/     
    156264        int32_t physical_minimum;
    157         /** */ 
     265
     266        /** Maximal valid physical value */     
    158267        int32_t physical_maximum;
    159268
    160         /** */ 
     269        /** Items attributes*/ 
    161270        uint8_t item_flags;
    162271
     272        /** Report type */
    163273        usb_hid_report_type_t type;
    164274
    165275        /** current collection path*/   
    166276        usb_hid_report_path_t *usage_path;
    167         /** */ 
     277
     278        /** Unused*/   
    168279        link_t link;
    169280
    170281        int in_delimiter;
    171282} usb_hid_report_item_t;
    172 
    173 /** HID parser callbacks for IN items. */
    174 typedef struct {
    175         /** Callback for keyboard.
    176          *
    177          * @param key_codes Array of pressed key (including modifiers).
    178          * @param count Length of @p key_codes.
    179          * @param arg Custom argument.
    180          */
    181         void (*keyboard)(const uint8_t *key_codes, size_t count, const uint8_t report_id, void *arg);
    182 } usb_hid_report_in_callbacks_t;
    183 
    184 
     283/*---------------------------------------------------------------------------*/
     284/**
     285 * Enum of the keyboard modifiers
     286 */
    185287typedef enum {
    186288        USB_HID_MOD_LCTRL = 0x01,
     
    206308        USB_HID_MOD_RGUI
    207309};
     310/*---------------------------------------------------------------------------*/
     311
    208312
    209313#endif
Note: See TracChangeset for help on using the changeset viewer.