Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/usbhid/include/usb/hid/hid_report_items.h

    r74b1e40 r160b75e  
    2727 */
    2828
    29 /** @addtogroup libusb
     29/** @addtogroup libusbhid
    3030 * @{
    3131 */
    3232/** @file
    33  * @brief USB HID Report descriptor item tags.
     33 * @brief USB HID parser.
    3434 */
    35 #ifndef LIBUSB_HID_REPORT_ITEMS_H_
    36 #define LIBUSB_HID_REPORT_ITEMS_H_
     35#ifndef LIBUSBHID_HID_REPORT_ITEMS_H_
     36#define LIBUSBHID_HID_REPORT_ITEMS_H_
    3737
    3838#include <stdint.h>
    3939
    40 /*---------------------------------------------------------------------------*/
    41 /*
     40/**
    4241 * Item prefix
    4342 */
    44 
    45 /** Returns size of item data in bytes */
    4643#define USB_HID_ITEM_SIZE(data)         ((uint8_t)(data & 0x3))
    47 
    48 /** Returns item tag */
    4944#define USB_HID_ITEM_TAG(data)          ((uint8_t)((data & 0xF0) >> 4))
    50 
    51 /** Returns class of item tag */
    5245#define USB_HID_ITEM_TAG_CLASS(data)    ((uint8_t)((data & 0xC) >> 2))
    53 
    54 /** Returns if the item is the short item or long item. Long items are not
    55  * supported. */
    5646#define USB_HID_ITEM_IS_LONG(data)      (data == 0xFE)
    5747
    58 /*---------------------------------------------------------------------------*/
    59 /*
    60  * Extended usage macros
    61  */
    6248
    63 /** Recognizes if the given usage is extended (contains also usage page).  */
    64 #define USB_HID_IS_EXTENDED_USAGE(usage)        ((usage & 0xFFFF0000) != 0)
    65 
    66 /** Cuts usage page of the extended usage. */
    67 #define USB_HID_EXTENDED_USAGE_PAGE(usage)      ((usage & 0xFFFF0000) >> 16)
    68 
    69 /** Cuts usage of the extended usage */
    70 #define USB_HID_EXTENDED_USAGE(usage)           (usage & 0xFFFF)
    71 
    72 /*---------------------------------------------------------------------------*/
    73 /*
     49/**
    7450 * Input/Output/Feature Item flags
    7551 */
    76 /**
    77  * Indicates whether the item is data (0) or a constant (1) value. Data
    78  * indicates the item is defining report fields that contain modifiable device
    79  * data. Constant indicates the item is a static read-only field in a report
    80  * and cannot be modified (written) by the host.
    81  */
     52/** Constant (1) / Variable (0) */
    8253#define USB_HID_ITEM_FLAG_CONSTANT(flags)       ((flags & 0x1) == 0x1)
    83 
    84 /**
    85  * Indicates whether the item creates variable (1) or array (0) data fields in
    86  * reports.
    87  */
     54/** Variable (1) / Array (0) */
    8855#define USB_HID_ITEM_FLAG_VARIABLE(flags)       ((flags & 0x2) == 0x2)
    89 
    90 /**
    91  * Indicates whether the data is absolute (0) (based on a fixed origin) or
    92  * relative (1) (indicating the change in value from the last report). Mouse
    93  * devices usually provide relative data, while tablets usually provide
    94  * absolute data.
    95  */
     56/** Absolute / Relative*/
    9657#define USB_HID_ITEM_FLAG_RELATIVE(flags)       ((flags & 0x4) == 0x4)
    97 
    98 /**
    99  * Indicates whether the data “rolls over” when reaching either the extreme
    100  * high or low value. For example, a dial that can spin freely 360 degrees
    101  * might output values from 0 to 10. If Wrap is indicated, the next value
    102  * reported after passing the 10 position in the increasing direction would be
    103  * 0.
    104  */
     58/** Wrap / No Wrap */
    10559#define USB_HID_ITEM_FLAG_WRAP(flags)           ((flags & 0x8) == 0x8)
    106 
    107 /**
    108  * Indicates whether the raw data from the device has been processed in some
    109  * way, and no longer represents a linear relationship between what is
    110  * measured and the data that is reported.
    111  */
    11260#define USB_HID_ITEM_FLAG_LINEAR(flags)         ((flags & 0x10) == 0x10)
    113 
    114 /**
    115  * Indicates whether the control has a preferred state to which it will return
    116  * when the user is not physically interacting with the control. Push buttons
    117  * (as opposed to toggle buttons) and self- centering joysticks are examples.
    118  */
    11961#define USB_HID_ITEM_FLAG_PREFERRED(flags)      ((flags & 0x20) == 0x20)
    120 
    121 /**
    122  * Indicates whether the control has a state in which it is not sending
    123  * meaningful data. One possible use of the null state is for controls that
    124  * require the user to physically interact with the control in order for it to
    125  * report useful data.
    126  */
    12762#define USB_HID_ITEM_FLAG_POSITION(flags)       ((flags & 0x40) == 0x40)
    128 
    129 /**
    130  * Indicates whether the Feature or Output control's value should be changed
    131  * by the host or not.  Volatile output can change with or without host
    132  * interaction. To avoid synchronization problems, volatile controls should be
    133  * relative whenever possible.
    134  */
    13563#define USB_HID_ITEM_FLAG_VOLATILE(flags)       ((flags & 0x80) == 0x80)
    136 
    137 /**
    138  * Indicates that the control emits a fixed-size stream of bytes. The contents
    139  * of the data field are determined by the application. The contents of the
    140  * buffer are not interpreted as a single numeric quantity. Report data
    141  * defined by a Buffered Bytes item must be aligned on an 8-bit boundary.
    142  */
    14364#define USB_HID_ITEM_FLAG_BUFFERED(flags)       ((flags & 0x100) == 0x100)
    14465
    145 /*---------------------------------------------------------------------------*/
    146 
    14766/* MAIN ITEMS */
    148 
    149 /**
    150  * Main items are used to either define or group certain types of data fields
    151  * within a Report descriptor.
    152  */
    153 #define USB_HID_TAG_CLASS_MAIN                  0x0
    154 
    155 /**
    156  * An Input item describes information about the data provided by one or more
    157  * physical controls. An application can use this information to interpret the
    158  * data provided by the device. All data fields defined in a single item share
    159  * an identical data format.
    160  */
    161 #define USB_HID_REPORT_TAG_INPUT                0x8
    162 
    163 /**
    164  * The Output item is used to define an output data field in a report. This
    165  * item is similar to an Input item except it describes data sent to the
    166  * device—for example, LED states.
    167  */
    168 #define USB_HID_REPORT_TAG_OUTPUT               0x9
    169 
    170 /**
    171  * Feature items describe device configuration information that can be sent to
    172  * the device.
    173  */
    174 #define USB_HID_REPORT_TAG_FEATURE              0xB
    175 
    176 /**
    177  * A Collection item identifies a relationship between two or more data
    178  * (Input, Output, or Feature.)
    179  */
     67#define USB_HID_TAG_CLASS_MAIN                          0x0
     68#define USB_HID_REPORT_TAG_INPUT                        0x8
     69#define USB_HID_REPORT_TAG_OUTPUT                       0x9
     70#define USB_HID_REPORT_TAG_FEATURE                      0xB
    18071#define USB_HID_REPORT_TAG_COLLECTION           0xA
    181 
    182 /**
    183  * While the Collection item opens a collection of data, the End Collection
    184  * item closes a collection.
    185  */
    18672#define USB_HID_REPORT_TAG_END_COLLECTION       0xC
    18773
    188 /*---------------------------------------------------------------------------*/
     74/* GLOBAL ITEMS */
     75#define USB_HID_TAG_CLASS_GLOBAL                        0x1
     76#define USB_HID_REPORT_TAG_USAGE_PAGE           0x0
     77#define USB_HID_REPORT_TAG_LOGICAL_MINIMUM      0x1
     78#define USB_HID_REPORT_TAG_LOGICAL_MAXIMUM      0x2
     79#define USB_HID_REPORT_TAG_PHYSICAL_MINIMUM 0x3
     80#define USB_HID_REPORT_TAG_PHYSICAL_MAXIMUM 0x4
     81#define USB_HID_REPORT_TAG_UNIT_EXPONENT        0x5
     82#define USB_HID_REPORT_TAG_UNIT                         0x6
     83#define USB_HID_REPORT_TAG_REPORT_SIZE          0x7
     84#define USB_HID_REPORT_TAG_REPORT_ID            0x8
     85#define USB_HID_REPORT_TAG_REPORT_COUNT         0x9
     86#define USB_HID_REPORT_TAG_PUSH                         0xA
     87#define USB_HID_REPORT_TAG_POP                          0xB
    18988
    190 /* GLOBAL ITEMS */
    191 
    192 /**
    193  * Global items describe rather than define data from a control.
    194  */
    195 #define USB_HID_TAG_CLASS_GLOBAL                0x1
    196 
    197 /**
    198  * Unsigned integer specifying the current Usage Page. Since a usage are 32
    199  * bit values, Usage Page items can be used to conserve space in a report
    200  * descriptor by setting the high order 16 bits of a subsequent usages. Any
    201  * usage that follows which is defines 16 bits or less is interpreted as a
    202  * Usage ID and concatenated with the Usage Page to form a 32 bit Usage.
    203  */
    204 #define USB_HID_REPORT_TAG_USAGE_PAGE           0x0
    205 
    206 /**
    207  * Extent value in logical units. This is the minimum value that a variable
    208  * or array item will report. For example, a mouse reporting x position values
    209  * from 0 to 128 would have a Logical Minimum of 0 and a Logical Maximum of
    210  * 128.
    211  */
    212 #define USB_HID_REPORT_TAG_LOGICAL_MINIMUM      0x1
    213 
    214 /**
    215  * Extent value in logical units. This is the maximum value that a variable
    216  * or array item will report.
    217  */
    218 #define USB_HID_REPORT_TAG_LOGICAL_MAXIMUM      0x2
    219 
    220 /**
    221  * Minimum value for the physical extent of a variable item. This represents
    222  * the Logical Minimum with units applied to it.
    223  */
    224 #define USB_HID_REPORT_TAG_PHYSICAL_MINIMUM     0x3
    225 
    226 /**
    227  * Maximum value for the physical extent of a variable item.
    228  */
    229 #define USB_HID_REPORT_TAG_PHYSICAL_MAXIMUM     0x4
    230 
    231 /**
    232  * Value of the unit exponent in base 10. See the table later in this section
    233  * for more information.
    234  */
    235 #define USB_HID_REPORT_TAG_UNIT_EXPONENT        0x5
    236 
    237 /**
    238  * Unit values.
    239  */
    240 #define USB_HID_REPORT_TAG_UNIT                 0x6
    241 
    242 /**
    243  * Unsigned integer specifying the size of the report fields in bits. This
    244  * allows the parser to build an item map for the report handler to use.
    245  */
    246 #define USB_HID_REPORT_TAG_REPORT_SIZE          0x7
    247 
    248 /**
    249  * Unsigned value that specifies the Report ID. If a Report ID tag is used
    250  * anywhere in Report descriptor, all data reports for the device are preceded
    251  * by a single byte ID field. All items succeeding the first Report ID tag but
    252  * preceding a second Report ID tag are included in a report prefixed by a
    253  * 1-byte ID. All items succeeding the second but preceding a third Report ID
    254  * tag are included in a second report prefixed by a second ID, and so on.
    255  */
    256 #define USB_HID_REPORT_TAG_REPORT_ID            0x8
    257 
    258 /**
    259  * Unsigned integer specifying the number of data fields for the item;
    260  * determines how many fields are included in the report for this particular
    261  * item (and consequently how many bits are added to the report).
    262  */
    263 #define USB_HID_REPORT_TAG_REPORT_COUNT         0x9
    264 
    265 /**
    266  * Places a copy of the global item state table on the stack.
    267  */
    268 #define USB_HID_REPORT_TAG_PUSH                 0xA
    269 
    270 /**
    271  * Replaces the item state table with the top structure from the stack.
    272  */
    273 #define USB_HID_REPORT_TAG_POP                  0xB
    274 
    275 /*---------------------------------------------------------------------------*/
    27689
    27790/* LOCAL ITEMS */
    278 
    279 /**
    280  * Local item tags define characteristics of controls. These items do not
    281  * carry over to the next Main item. If a Main item defines more than one
    282  * control, it may be preceded by several similar Local item tags. For
    283  * example, an Input item may have several Usage tags associated with it, one
    284  * for each control.
    285  */
    286 #define USB_HID_TAG_CLASS_LOCAL                 0x2
    287 
    288 /**
    289  * Usage index for an item usage; represents a suggested usage for the item or
    290  * collection. In the case where an item represents multiple controls, a Usage
    291  * tag may suggest a usage for every variable or element in an array.
    292  */
    293 #define USB_HID_REPORT_TAG_USAGE                0x0
    294 
    295 /**
    296  * Defines the starting usage associated with an array or bitmap.
    297  */
    298 #define USB_HID_REPORT_TAG_USAGE_MINIMUM        0x1
    299 
    300 /**
    301  * Defines the ending usage associated with an array or bitmap.
    302  */
    303 #define USB_HID_REPORT_TAG_USAGE_MAXIMUM        0x2
    304 
    305 /**
    306  * Determines the body part used for a control. Index points to a designator
    307  * in the Physical descriptor.
    308  */
    309 #define USB_HID_REPORT_TAG_DESIGNATOR_INDEX     0x3
    310 
    311 /**
    312  * Defines the index of the starting designator associated with an array or
    313  * bitmap.
    314  */
     91#define USB_HID_TAG_CLASS_LOCAL                                 0x2
     92#define USB_HID_REPORT_TAG_USAGE                                0x0
     93#define USB_HID_REPORT_TAG_USAGE_MINIMUM                0x1
     94#define USB_HID_REPORT_TAG_USAGE_MAXIMUM                0x2
     95#define USB_HID_REPORT_TAG_DESIGNATOR_INDEX             0x3
    31596#define USB_HID_REPORT_TAG_DESIGNATOR_MINIMUM   0x4
    316 
    317 /**
    318  * Defines the index of the ending designator associated with an array or
    319  * bitmap.
    320  */
    32197#define USB_HID_REPORT_TAG_DESIGNATOR_MAXIMUM   0x5
    322 
    323 /**
    324  * String index for a String descriptor; allows a string to be associated with
    325  * a particular item or control.
    326  */
    327 #define USB_HID_REPORT_TAG_STRING_INDEX         0x7
    328 
    329 /**
    330  * Specifies the first string index when assigning a group of sequential
    331  * strings to controls in an array or bitmap.
    332  */
    333 #define USB_HID_REPORT_TAG_STRING_MINIMUM       0x8
    334 
    335 /**
    336  * Specifies the last string index when assigning a group of sequential
    337  * strings to controls in an array or bitmap.
    338  */
    339 #define USB_HID_REPORT_TAG_STRING_MAXIMUM       0x9
    340 
    341 /**
    342  * Defines the beginning or end of a set of local items (1 = open set, 0 =
    343  * close set).
    344  *
    345  * Usages other than the first (most preferred) usage defined are not
    346  * accessible by system software.
    347  */
    348 #define USB_HID_REPORT_TAG_DELIMITER            0xA
    349 
    350 /*---------------------------------------------------------------------------*/
     98#define USB_HID_REPORT_TAG_STRING_INDEX                 0x7
     99#define USB_HID_REPORT_TAG_STRING_MINIMUM               0x8
     100#define USB_HID_REPORT_TAG_STRING_MAXIMUM               0x9
     101#define USB_HID_REPORT_TAG_DELIMITER                    0xA
    351102
    352103#endif
Note: See TracChangeset for help on using the changeset viewer.