?lang_form? ?lang_select? ?lang_submit? ?lang_endform?
{HEADER END}
{BLAME START}

library

?curdirlinks? -

Blame information for rev 32

Line No. Rev Author Line
1 32 kaklik /******************************************************************************
2  
3 USB Host Human Interface Device Parser Header File
4  
5 Summary:
6 This is the header file for a USB Embedded Host that is Human Interface
7 Device Class . This header file contains HID parser related informaton.
8  
9 Description:
10 This is the header file for a USB Embedded Host that is Human Interface
11 Device Class .
12  
13 This file should be included with usb_host.h to provide the USB hardware
14 interface. It must be included after the application-specific usb_config.h
15 file and after the USB Embedded Host header file usb_host.h, as definitions
16 in those files are required for proper compilation. This file contains HID
17 parser related definitions.
18  
19 Acronyms/abbreviations used by this class:
20 * HID - Human Interface Device
21  
22 Every HID class device identifies itself with a report descriptor. A Report
23 descriptor describes each piece of data that the device generates and
24 what the data is actually measuring. A parser is needed to decode the
25 content of report descriptor.
26  
27 Report descriptors are composed of pieces of information. Each piece of
28 information is called an Item.
29 HID Item Header
30  
31 ---------------------------------------------------------
32 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
33 | Tag | Type | Size |
34 ---------------------------------------------------------
35  
36 The HID class driver contains a parser used to analyze items found in the Report
37 descriptor. The parser extracts information from the descriptor in a linear fashion.
38 The parser collects the state of each known item as it walks through the
39 descriptor, and stores them in an item state table.
40  
41 Any HID device to be compliant must have a valid report descriptor.
42 Micochip HID host stack comes with a HID parser that does basic sanity check
43 and provides interface functions to understand the reports transmitted
44 from the device. Refer HID firmware specifications to understand parser.
45 This file contains data structures that stores parsed information in more
46 accessible format.
47  
48  
49 *******************************************************************************/
50 //DOM-IGNORE-BEGIN
51 /*******************************************************************************
52  
53 * FileName: usb_host_hid_parser.h
54 * Dependencies: None
55 * Processor: PIC24/dsPIC30/dsPIC33/PIC32MX
56 * Compiler: C30 v2.01/C32 v0.00.18
57 * Company: Microchip Technology, Inc.
58  
59 Software License Agreement
60  
61 The software supplied herewith by Microchip Technology Incorporated
62 (the “Company”) for its PICmicro® Microcontroller is intended and
63 supplied to you, the Company’s customer, for use solely and
64 exclusively on Microchip PICmicro Microcontroller products. The
65 software is owned by the Company and/or its supplier, and is
66 protected under applicable copyright laws. All rights are reserved.
67 Any use in violation of the foregoing restrictions may subject the
68 user to criminal sanctions under applicable laws, as well as to
69 civil liability for the breach of the terms and conditions of this
70 license.
71  
72 THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
73 WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
74 TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
75 PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
76 IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
77 CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
78  
79 Change History:
80 Rev Description
81 ----- --------------------------------
82 2.6a- No change
83 2.7a
84 *******************************************************************************/
85 //DOM-IGNORE-END
86  
87 //DOM-IGNORE-BEGIN
88 #ifndef _USB_HOST_HID_PARSER_H_ /* usb_host_hid_parser.h */
89 #define _USB_HOST_HID_PARSER_H_
90 //DOM-IGNORE-END
91  
92  
93 #define HIDItem_SizeMask 0x03 // Mask for Size bitfield in Item header
94 #define HIDItem_TagMask 0xF0 // Mask for Tag bitfield in Item header
95 #define HIDItem_TagShift 0x04 // Shift Value for Tag bitfield in Item header
96 #define HIDItem_TypeMask 0xC // Mask for Type bitfield in Item header
97 #define HIDItem_TypeShift 0x02 // Shift Value for Tag bitfield
98  
99 //------------------------------------------------------------------------------
100 //
101 // HID Item Type Definitions
102 //
103 //------------------------------------------------------------------------------
104  
105 #define HIDType_Main 0 // Main Item value
106 #define HIDType_Global 1 // Global Item value
107 #define HIDType_Local 2 // Local Item value
108 #define HIDType_Long 3 // Long Item value
109  
110 //------------------------------------------------------------------------------
111 //
112 // HID Item Tag Definitions - Main Items
113 //
114 //------------------------------------------------------------------------------
115  
116 #define HIDTag_Input 0x08 // Input Tag value
117 #define HIDTag_Output 0x09 // Output Tag value
118 #define HIDTag_Collection 0x0A // Collection Tag value
119 #define HIDTag_Feature 0x0B // Feature Tag value
120 #define HIDTag_EndCollection 0x0C // End of Collection Tag value
121  
122 //------------------------------------------------------------------------------
123 //
124 // HID Item Tag Definitions - Globals
125 //
126 //------------------------------------------------------------------------------
127 #define HIDTag_UsagePage 0x00 // UsagePage Tag value
128 #define HIDTag_LogicalMinimum 0x01 // Logical Minimum Tag value
129 #define HIDTag_LogicalMaximum 0x02 // Logical Maximum Tag value
130 #define HIDTag_PhysicalMinimum 0x03 // Physical Minimum Tag value
131 #define HIDTag_PhysicalMaximum 0x04 // Physical Maximum Tag value
132 #define HIDTag_UnitExponent 0x05 // Unit Exponent Tag value
133 #define HIDTag_Unit 0x06 // Unit Tag value
134 #define HIDTag_ReportSize 0x07 // Report Size Tag value
135 #define HIDTag_ReportID 0x08 // Report ID Tag value
136 #define HIDTag_ReportCount 0x09 // ReportCount Tag value
137 #define HIDTag_Push 0x0A // Push Tag value
138 #define HIDTag_Pop 0x0B // Pop Tag value
139  
140 //------------------------------------------------------------------------------
141 //
142 // HID Item Tag Definitions - Locals
143 //
144 //------------------------------------------------------------------------------
145  
146 #define HIDTag_Usage 0x00 // Usage Tag value
147 #define HIDTag_UsageMinimum 0x01 // Usage Minimum Tag value
148 #define HIDTag_UsageMaximum 0x02 // Usage Maximum Tag value
149 #define HIDTag_DesignatorIndex 0x03 // Designator Index Tag value
150 #define HIDTag_DesignatorMinimum 0x04 // Designator Minimum Tag value
151 #define HIDTag_DesignatorMaximum 0x05 // Designator Maximum Tag value
152 #define HIDTag_StringIndex 0x07 // String Index Tag value
153 #define HIDTag_StringMinimum 0x08 // String Minimum Tag value
154 #define HIDTag_StringMaximum 0x09 // String Maximum Tag value
155 #define HIDTag_SetDelimiter 0x0A // Set Delimiter Tag value
156  
157 //------------------------------------------------------------------------------
158 //
159 // HID Main Item Header Bit Definitions
160 //
161 //------------------------------------------------------------------------------
162  
163 #define HIDData_BufferedBytes 0x100 // HID data bytes are bufferred
164 #define HIDData_VolatileBit 0x80 // Volatile bit position
165 #define HIDData_Volatile 0x80 // HID data is voaltile
166 #define HIDData_NullStateBit 0x40 // NULL state bit position
167 #define HIDData_NullState 0x40 // NULL state defined
168 #define HIDData_NoPreferredBit 0x20 // No Preferred bt position
169 #define HIDData_NoPreferred 0x20 // HID data type No Preferred
170 #define HIDData_NonlinearBit 0x10 // NonLinear bit position
171 #define HIDData_Nonlinear 0x10 // HID data type NonLinear
172 #define HIDData_WrapBit 0x08 // Wrap bit position
173 #define HIDData_Wrap 0x08 // HID data type Wrap
174 #define HIDData_RelativeBit 0x04 // Relative bit position
175 #define HIDData_Relative 0x04 // HID data type relative
176 #define HIDData_Absolute 0x00 // HID data type absolute
177 #define HIDData_VariableBit 0x02 // Variable bit position
178 #define HIDData_Variable 0x02 // HID data type variable
179 #define HIDData_ArrayBit 0x02 // Array Bit position
180 #define HIDData_Array 0x00 // Array indentifier value
181 #define HIDData_ConstantBit 0x01 // Constant Bit position
182 #define HIDData_Constant 0x01 // Constant data type indentifier value
183  
184 //------------------------------------------------------------------------------
185 //
186 // HID Collection Data Definitions
187 //
188 //------------------------------------------------------------------------------
189 #define HIDCollection_Physical 0x00
190 #define HIDCollection_Application 0x01
191  
192  
193 typedef enum {
194 hidReportInput,
195 hidReportOutput,
196 hidReportFeature,
197 hidReportUnknown
198 } HIDReportTypeEnum;
199  
200  
201  
202 // *****************************************************************************
203 /* HID Item Information
204  
205 This structure contains information about each Item of the report descriptor.
206 */
207 typedef struct _HID_ITEM_INFO
208 {
209 union
210 {
211 struct
212 {
213 BYTE ItemSize :2; // Numeric expression specifying size of data
214 BYTE ItemType :2; // This field identifies type of item(Main, Global or Local)
215 BYTE ItemTag :4; // This field specifies the function of the item
216 };
217 BYTE val; // to access the data in byte format
218 } ItemDetails;
219  
220 union
221 {
222 LONG sItemData; // Item Data is stored in signed format
223 DWORD uItemData; // Item Data is stored in unsigned format
224 BYTE bItemData[4];
225 } Data;
226 } HID_ITEM_INFO;
227  
228  
229 // *****************************************************************************
230 /* HID Global Item Information
231  
232 This structure contains information about each Global Item of the report descriptor.
233 */
234 typedef struct _HID_GLOBALS
235 {
236 WORD usagePage; // Specifies current Usage Page
237 LONG logicalMinimum; // This is the minimum value that a variable or array item will report
238 LONG logicalMaximum; // This is the maximum value that a variable or array item will report
239 LONG physicalMinimum; // Minimum value for the physical extent of a variable item
240 LONG physicalMaximum; // Maximum value for the physical extent of a variable item
241 LONG unitExponent; // Value of the unit exponent in base 10
242 LONG unit; // Unit values
243 WORD reportIndex; // Conter to keep track of report being processed in the parser
244 BYTE reportID; // Report ID. All the reports are preceded by a single byte report ID
245 BYTE reportsize; // Size of current report in bytes
246 BYTE reportCount; // This field determines number of fields in the report
247  
248 } HID_GLOBALS;
249  
250 // *****************************************************************************
251 /* HID Report details
252  
253 This structure contains information about each report exchanged with the device.
254 */
255 typedef struct _HID_REPORT
256 {
257 WORD reportID; // Report ID of the associated report
258 WORD inputBits; // If input report then length of report in bits
259 WORD outputBits; // If output report then length of report in bits
260 WORD featureBits; // If feature report then length of report in bits
261 } HID_REPORT;
262  
263  
264 // *****************************************************************************
265 /* HID Collection Details
266  
267 This structure contains information about each collection encountered in the report descriptor.
268 */
269 typedef struct _HID_COLLECTION
270 {
271 DWORD data; // Collection raw data
272 WORD usagePage; // Usage page associated with current level of collection
273 BYTE firstUsageItem; // Index of First Usage Item in the current collection
274 BYTE usageItems; // Number of Usage Items in the current collection
275 BYTE firstReportItem; // Index of First report Item in the current collection
276 BYTE reportItems; // Number of report Items in the current collection
277 BYTE parent; // Index to Parent collection
278 BYTE firstChild; // Index to next child collection in the report descriptor
279 BYTE nextSibling; // Index to next child collection in the report descriptor
280 } HID_COLLECTION;
281  
282 // *****************************************************************************
283 /* HID Report Details
284  
285 This structure contains information about each Report encountered in the report descriptor.
286 */
287 typedef struct _HID_REPORTITEM
288 {
289 HIDReportTypeEnum reportType; // Type of Report Input/Output/Feature
290 HID_GLOBALS globals; // Stores all the global items associated with the current report
291 BYTE startBit; // Starting Bit Position of the report
292 BYTE parent; // Index of parent collection
293 DWORD dataModes; // this tells the data mode is array or not
294 BYTE firstUsageItem; // Index to first usage item related to the report
295 BYTE usageItems; // Number of usage items in the current report
296 BYTE firstStringItem; // Index to first srting item in the list
297 BYTE stringItems; // Number of string items in the current report
298 BYTE firstDesignatorItem; // Index to first designator item
299 BYTE designatorItems; // Number of designator items in the current report
300 } HID_REPORTITEM;
301  
302 // *****************************************************************************
303 /* HID Report Details
304  
305 This structure contains information about each Usage Item encountered in the report descriptor.
306 */
307 typedef struct _HID_USAGEITEM
308 {
309 BOOL isRange; // True if Usage item has a valid MAX and MIN range
310 WORD usagePage; // Usage page ID asscociated with the Item
311 WORD usage; // Usage ID asscociated with the Item
312 WORD usageMinimum; // Defines the starting usage associated with an array or bitmap
313 WORD usageMaximum; // Defines the ending usage associated with an array or bitmap
314 } HID_USAGEITEM;
315  
316 // *****************************************************************************
317 /* HID String Item Details
318  
319 This structure contains information about each Report encountered in the report descriptor.
320 */
321 typedef struct _HID_STRINGITEM
322 {
323 BOOL isRange; // If range of String Item is valid
324 WORD index; // String index for a String descriptor; allows a string to be associated with a particular item or control
325 WORD minimum; // Specifies the first string index when assigning a group of sequential strings to controls in an array or bitmap
326 WORD maximum; // Specifies the last string index when assigning a group of sequential strings to controls in an array or bitmap
327 } HID_STRINGITEM, HID_DESIGITEM;
328  
329  
330 // *****************************************************************************
331 /* Report Descriptor Information
332  
333 This structure contains top level information of the report descriptor. This information
334 is important and is used to understand the information during th ecourse of parsing.
335 This structure also stores temporary data needed during parsing the report descriptor.
336 All of this information may not be of much inportance to the application.
337 */
338 typedef struct _USB_HID_DEVICE_RPT_INFO
339 {
340 WORD reportPollingRate; // This stores the pollrate for the input report. Application can use this to decide the rate of transfer
341 BYTE interfaceNumber; // This stores the interface number for the current report descriptor
342  
343 // This set of members are used during parsing of Report descriptor , application does not normally need these details
344 BOOL haveDesignatorMax; // True if report descriptor has a valid Designator Max
345 BOOL haveDesignatorMin; // True if report descriptor has a valid Designator Min
346 BOOL haveStringMax; // True if report descriptor has a valid String Max
347 BOOL haveStringMin; // True if report descriptor has a valid String Min
348 BOOL haveUsageMax; // True if report descriptor has a valid Usage Max
349 BOOL haveUsageMin; // True if report descriptor has a valid Usage Min
350 WORD designatorMaximum; // Last designator max value
351 WORD designatorMinimum; // Last designator min value
352 WORD designatorRanges; // Last designator range
353 WORD designators; // This tells toatal number of designator items
354 WORD rangeUsagePage; // current usage page during parsing
355 WORD stringMaximum; // current string maximum
356 WORD stringMinimum; // current string minimum
357 WORD stringRanges; // current string ranges
358 WORD usageMaximum; // current usage maximum
359 WORD usageMinimum; // current usage minimum
360 WORD usageRanges; // current usage ranges
361 BYTE collectionNesting; // this number tells depth of collection nesting
362 BYTE collections; // total number of collections
363 BYTE designatorItems; // total number of designator items
364 BYTE firstUsageItem; // index of first usage item for the current collection
365 BYTE firstDesignatorItem; // index of first designator item for the current collection
366 BYTE firstStringItem; // index of first string item for the current collection
367 BYTE globalsNesting; // On encountering every PUSH item , this is incremented , keep track of current depth of Globals
368 BYTE maxCollectionNesting; // Maximum depth of collections
369 BYTE maxGlobalsNesting; // Maximum depth of Globals
370 BYTE parent; // Parent collection
371 BYTE reportItems; // total number of report items
372 BYTE reports; // total number of reports
373 BYTE sibling; // current sibling collection
374 BYTE stringItems; // total number of string items , used to index the array of strings
375 BYTE strings; // total sumber of strings
376 BYTE usageItems; // total number of usage items , used to index the array of usage
377 BYTE usages; // total sumber of usages
378 HID_GLOBALS globals; // holds cuurent globals items
379  
380 } USB_HID_DEVICE_RPT_INFO;
381  
382  
383 // *****************************************************************************
384 /* List of Items
385  
386 This structure contains array of pointers to all the Items in the report descriptor.
387 HID parser will populate the lists while parsing the report descriptor. This data is
388 used by interface functions provided in file usb_host_hid_interface.c to retrive data
389 from the report received from the device. Application can also access these details
390 to retreive the intended information incase provided interface function fail to do so.
391 */
392 typedef struct _USB_HID_ITEM_LIST
393 {
394 HID_COLLECTION *collectionList; // List of collections, see HID_COLLECTION for details in the structure
395 HID_DESIGITEM *designatorItemList; // List of designator Items, see HID_DESIGITEM for details in the structure
396 HID_GLOBALS *globalsStack; // List of global Items, see HID_GLOBALS for details in the structure
397 HID_REPORTITEM *reportItemList; // List of report Items, see HID_REPORTITEM for details in the structure
398 HID_REPORT *reportList; // List of reports , see HID_REPORT for details in the structure
399 HID_STRINGITEM *stringItemList; // List of string item , see HID_STRINGITEM for details in the structure
400 HID_USAGEITEM *usageItemList; // List of Usage item , see HID_USAGEITEM for details in the structure
401 BYTE *collectionStack; // stores the array of parents ids for the collection
402 } USB_HID_ITEM_LIST;
403  
404 // *****************************************************************************
405 /* HID parser error codes
406  
407 This enumerates the error encountered during the parsing of report descriptor. In case of any error
408 parsing is sttopped and the error is flagged. Device is not attched successfully.
409 */
410 typedef enum {
411 HID_ERR = 0, // No error
412 HID_ERR_NotEnoughMemory, // If not enough Heap can be allocated, make sure sufficient dynamic memory is aloocated for the parser
413 HID_ERR_NullPointer, // Pointer to report descriptor is NULL
414 HID_ERR_UnexpectedEndCollection, // End of collection not expected
415 HID_ERR_UnexpectedPop, // POP not expected
416 HID_ERR_MissingEndCollection, // No end of collection found
417 HID_ERR_MissingTopLevelCollection, // Atleast one collection must be present
418 HID_ERR_NoReports, // atlest one report must be present
419 HID_ERR_UnmatchedUsageRange, // Either Minimum or Maximum for usage range missing
420 HID_ERR_UnmatchedStringRange, // Either Minimum or Maximum for string range missing
421 HID_ERR_UnmatchedDesignatorRange, // Either Minimum or Maximum for designator range missing
422 HID_ERR_UnexpectedEndOfDescriptor, // Report descriptor not formatted properly
423 HID_ERR_BadLogicalMin, // Logical Min greater than report size
424 HID_ERR_BadLogicalMax, // Logical Max greater than report size
425 HID_ERR_BadLogical, // If logical Min is greater than Max
426 HID_ERR_ZeroReportSize, // Report size is zero
427 HID_ERR_ZeroReportID, // report ID is zero
428 HID_ERR_ZeroReportCount, // Number of reports is zero
429 HID_ERR_BadUsageRangePage, // Bad Usage page range
430 HID_ERR_BadUsageRange // Bad Usage range
431 } USB_HID_RPT_DESC_ERROR;
432  
433 /****************************************************************************
434 Function:
435 BOOL USBHostHID_HasUsage(HID_REPORTITEM *reportItem,WORD usagePage,
436 WORD usage,WORD *pindex)
437  
438 Description:
439 This function is used to locate the usage in a report descriptor.
440 Function will look into the data structures created by the HID parser
441 and return the appropriate location.
442  
443 Precondition:
444 None
445  
446 Parameters:
447 HID_REPORTITEM *reportItem - Report item index to be searched
448 WORD usagePage - Application needs to pass the usagePage as
449 the search criteria for the usage
450 WORD usage - Application needs to pass the usageto be
451 searched
452 WORD *pindex - returns index to the usage item requested.
453  
454 Return Values:
455 BOOL - FALSE - If requested usage is not found
456 TRUE - if requested usage is found
457 Remarks:
458 None
459 ***************************************************************************/
460 BOOL USBHostHID_HasUsage(HID_REPORTITEM *reportItem,WORD usagePage, WORD usage,WORD *pindex,BYTE* count);
461  
462  
463 //******************************************************************************
464 //******************************************************************************
465 // Section: External Variables
466 //******************************************************************************
467 //******************************************************************************
468  
469 extern USB_HID_DEVICE_RPT_INFO deviceRptInfo;
470 extern USB_HID_ITEM_LIST itemListPtrs;
471  
472 #endif /* usb_host_hid_parser.h */
{BLAME END}
{FOOTER START}

Powered by WebSVN v2.8.3