source: mainline/uspace/lib/usbhid/include/usb/hid/hid_report_items.h

Last change on this file was 09ab0a9a, checked in by Jiri Svoboda <jiri@…>, 7 years ago

Fix vertical spacing with new Ccheck revision.

  • Property mode set to 100644
File size: 11.2 KB
Line 
1/*
2 * Copyright (c) 2011 Matej Klonfar
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * - Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 * - The name of the author may not be used to endorse or promote products
15 * derived from this software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29/** @addtogroup libusb
30 * @{
31 */
32/** @file
33 * @brief USB HID Report descriptor item tags.
34 */
35#ifndef LIBUSB_HID_REPORT_ITEMS_H_
36#define LIBUSB_HID_REPORT_ITEMS_H_
37
38#include <stdint.h>
39
40/*
41 * Item prefix
42 */
43
44/** Returns size of item data in bytes */
45#define USB_HID_ITEM_SIZE(data) ((uint8_t)(data & 0x3))
46
47/** Returns item tag */
48#define USB_HID_ITEM_TAG(data) ((uint8_t)((data & 0xF0) >> 4))
49
50/** Returns class of item tag */
51#define USB_HID_ITEM_TAG_CLASS(data) ((uint8_t)((data & 0xC) >> 2))
52
53/** Returns if the item is the short item or long item. Long items are not
54 * supported.
55 */
56#define USB_HID_ITEM_IS_LONG(data) (data == 0xFE)
57
58/*
59 * Extended usage macros
60 */
61
62/** Recognizes if the given usage is extended (contains also usage page). */
63#define USB_HID_IS_EXTENDED_USAGE(usage) ((usage & 0xFFFF0000) != 0)
64
65/** Cuts usage page of the extended usage. */
66#define USB_HID_EXTENDED_USAGE_PAGE(usage) ((usage & 0xFFFF0000) >> 16)
67
68/** Cuts usage of the extended usage */
69#define USB_HID_EXTENDED_USAGE(usage) (usage & 0xFFFF)
70
71/*
72 * Input/Output/Feature Item flags
73 */
74/**
75 * Indicates whether the item is data (0) or a constant (1) value. Data
76 * indicates the item is defining report fields that contain modifiable device
77 * data. Constant indicates the item is a static read-only field in a report
78 * and cannot be modified (written) by the host.
79 */
80#define USB_HID_ITEM_FLAG_CONSTANT(flags) ((flags & 0x1) == 0x1)
81
82/**
83 * Indicates whether the item creates variable (1) or array (0) data fields in
84 * reports.
85 */
86#define USB_HID_ITEM_FLAG_VARIABLE(flags) ((flags & 0x2) == 0x2)
87
88/**
89 * Indicates whether the data is absolute (0) (based on a fixed origin) or
90 * relative (1) (indicating the change in value from the last report). Mouse
91 * devices usually provide relative data, while tablets usually provide
92 * absolute data.
93 */
94#define USB_HID_ITEM_FLAG_RELATIVE(flags) ((flags & 0x4) == 0x4)
95
96/** Indicates whether the data “rolls over” when reaching either the extreme
97 * high or low value. For example, a dial that can spin freely 360 degrees
98 * might output values from 0 to 10. If Wrap is indicated, the next value
99 * reported after passing the 10 position in the increasing direction would be
100 * 0.
101 */
102#define USB_HID_ITEM_FLAG_WRAP(flags) ((flags & 0x8) == 0x8)
103
104/**
105 * Indicates whether the raw data from the device has been processed in some
106 * way, and no longer represents a linear relationship between what is
107 * measured and the data that is reported.
108 */
109#define USB_HID_ITEM_FLAG_LINEAR(flags) ((flags & 0x10) == 0x10)
110
111/**
112 * Indicates whether the control has a preferred state to which it will return
113 * when the user is not physically interacting with the control. Push buttons
114 * (as opposed to toggle buttons) and self- centering joysticks are examples.
115 */
116#define USB_HID_ITEM_FLAG_PREFERRED(flags) ((flags & 0x20) == 0x20)
117
118/**
119 * Indicates whether the control has a state in which it is not sending
120 * meaningful data. One possible use of the null state is for controls that
121 * require the user to physically interact with the control in order for it to
122 * report useful data.
123 */
124#define USB_HID_ITEM_FLAG_POSITION(flags) ((flags & 0x40) == 0x40)
125
126/**
127 * Indicates whether the Feature or Output control's value should be changed
128 * by the host or not. Volatile output can change with or without host
129 * interaction. To avoid synchronization problems, volatile controls should be
130 * relative whenever possible.
131 */
132#define USB_HID_ITEM_FLAG_VOLATILE(flags) ((flags & 0x80) == 0x80)
133
134/**
135 * Indicates that the control emits a fixed-size stream of bytes. The contents
136 * of the data field are determined by the application. The contents of the
137 * buffer are not interpreted as a single numeric quantity. Report data
138 * defined by a Buffered Bytes item must be aligned on an 8-bit boundary.
139 */
140#define USB_HID_ITEM_FLAG_BUFFERED(flags) ((flags & 0x100) == 0x100)
141
142/* MAIN ITEMS */
143
144/**
145 * Main items are used to either define or group certain types of data fields
146 * within a Report descriptor.
147 */
148#define USB_HID_TAG_CLASS_MAIN 0x0
149
150/**
151 * An Input item describes information about the data provided by one or more
152 * physical controls. An application can use this information to interpret the
153 * data provided by the device. All data fields defined in a single item share
154 * an identical data format.
155 */
156#define USB_HID_REPORT_TAG_INPUT 0x8
157
158/**
159 * The Output item is used to define an output data field in a report. This
160 * item is similar to an Input item except it describes data sent to the
161 * device—for example, LED states.
162 */
163#define USB_HID_REPORT_TAG_OUTPUT 0x9
164
165/**
166 * Feature items describe device configuration information that can be sent to
167 * the device.
168 */
169#define USB_HID_REPORT_TAG_FEATURE 0xB
170
171/**
172 * A Collection item identifies a relationship between two or more data
173 * (Input, Output, or Feature.)
174 */
175#define USB_HID_REPORT_TAG_COLLECTION 0xA
176
177/**
178 * While the Collection item opens a collection of data, the End Collection
179 * item closes a collection.
180 */
181#define USB_HID_REPORT_TAG_END_COLLECTION 0xC
182
183/* GLOBAL ITEMS */
184
185/**
186 * Global items describe rather than define data from a control.
187 */
188#define USB_HID_TAG_CLASS_GLOBAL 0x1
189
190/**
191 * Unsigned integer specifying the current Usage Page. Since a usage are 32
192 * bit values, Usage Page items can be used to conserve space in a report
193 * descriptor by setting the high order 16 bits of a subsequent usages. Any
194 * usage that follows which is defines 16 bits or less is interpreted as a
195 * Usage ID and concatenated with the Usage Page to form a 32 bit Usage.
196 */
197#define USB_HID_REPORT_TAG_USAGE_PAGE 0x0
198
199/**
200 * Extent value in logical units. This is the minimum value that a variable
201 * or array item will report. For example, a mouse reporting x position values
202 * from 0 to 128 would have a Logical Minimum of 0 and a Logical Maximum of
203 * 128.
204 */
205#define USB_HID_REPORT_TAG_LOGICAL_MINIMUM 0x1
206
207/**
208 * Extent value in logical units. This is the maximum value that a variable
209 * or array item will report.
210 */
211#define USB_HID_REPORT_TAG_LOGICAL_MAXIMUM 0x2
212
213/**
214 * Minimum value for the physical extent of a variable item. This represents
215 * the Logical Minimum with units applied to it.
216 */
217#define USB_HID_REPORT_TAG_PHYSICAL_MINIMUM 0x3
218
219/**
220 * Maximum value for the physical extent of a variable item.
221 */
222#define USB_HID_REPORT_TAG_PHYSICAL_MAXIMUM 0x4
223
224/**
225 * Value of the unit exponent in base 10. See the table later in this section
226 * for more information.
227 */
228#define USB_HID_REPORT_TAG_UNIT_EXPONENT 0x5
229
230/**
231 * Unit values.
232 */
233#define USB_HID_REPORT_TAG_UNIT 0x6
234
235/**
236 * Unsigned integer specifying the size of the report fields in bits. This
237 * allows the parser to build an item map for the report handler to use.
238 */
239#define USB_HID_REPORT_TAG_REPORT_SIZE 0x7
240
241/**
242 * Unsigned value that specifies the Report ID. If a Report ID tag is used
243 * anywhere in Report descriptor, all data reports for the device are preceded
244 * by a single byte ID field. All items succeeding the first Report ID tag but
245 * preceding a second Report ID tag are included in a report prefixed by a
246 * 1-byte ID. All items succeeding the second but preceding a third Report ID
247 * tag are included in a second report prefixed by a second ID, and so on.
248 */
249#define USB_HID_REPORT_TAG_REPORT_ID 0x8
250
251/**
252 * Unsigned integer specifying the number of data fields for the item;
253 * determines how many fields are included in the report for this particular
254 * item (and consequently how many bits are added to the report).
255 */
256#define USB_HID_REPORT_TAG_REPORT_COUNT 0x9
257
258/**
259 * Places a copy of the global item state table on the stack.
260 */
261#define USB_HID_REPORT_TAG_PUSH 0xA
262
263/**
264 * Replaces the item state table with the top structure from the stack.
265 */
266#define USB_HID_REPORT_TAG_POP 0xB
267
268/* LOCAL ITEMS */
269
270/**
271 * Local item tags define characteristics of controls. These items do not
272 * carry over to the next Main item. If a Main item defines more than one
273 * control, it may be preceded by several similar Local item tags. For
274 * example, an Input item may have several Usage tags associated with it, one
275 * for each control.
276 */
277#define USB_HID_TAG_CLASS_LOCAL 0x2
278
279/**
280 * Usage index for an item usage; represents a suggested usage for the item or
281 * collection. In the case where an item represents multiple controls, a Usage
282 * tag may suggest a usage for every variable or element in an array.
283 */
284#define USB_HID_REPORT_TAG_USAGE 0x0
285
286/**
287 * Defines the starting usage associated with an array or bitmap.
288 */
289#define USB_HID_REPORT_TAG_USAGE_MINIMUM 0x1
290
291/**
292 * Defines the ending usage associated with an array or bitmap.
293 */
294#define USB_HID_REPORT_TAG_USAGE_MAXIMUM 0x2
295
296/**
297 * Determines the body part used for a control. Index points to a designator
298 * in the Physical descriptor.
299 */
300#define USB_HID_REPORT_TAG_DESIGNATOR_INDEX 0x3
301
302/**
303 * Defines the index of the starting designator associated with an array or
304 * bitmap.
305 */
306#define USB_HID_REPORT_TAG_DESIGNATOR_MINIMUM 0x4
307
308/**
309 * Defines the index of the ending designator associated with an array or
310 * bitmap.
311 */
312#define USB_HID_REPORT_TAG_DESIGNATOR_MAXIMUM 0x5
313
314/**
315 * String index for a String descriptor; allows a string to be associated with
316 * a particular item or control.
317 */
318#define USB_HID_REPORT_TAG_STRING_INDEX 0x7
319
320/**
321 * Specifies the first string index when assigning a group of sequential
322 * strings to controls in an array or bitmap.
323 */
324#define USB_HID_REPORT_TAG_STRING_MINIMUM 0x8
325
326/**
327 * Specifies the last string index when assigning a group of sequential
328 * strings to controls in an array or bitmap.
329 */
330#define USB_HID_REPORT_TAG_STRING_MAXIMUM 0x9
331
332/**
333 * Defines the beginning or end of a set of local items (1 = open set, 0 =
334 * close set).
335 *
336 * Usages other than the first (most preferred) usage defined are not
337 * accessible by system software.
338 */
339#define USB_HID_REPORT_TAG_DELIMITER 0xA
340
341#endif
342/**
343 * @}
344 */
Note: See TracBrowser for help on using the repository browser.