iokit/Families/IOHIDSystem/IOHIDDescriptorParser/HIDPriv.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 #ifndef __HIDPriv__
  23 #define __HIDPriv__
  24
  25 /*
  26         File:           HIDPriv.i
  27
  28         Contains:       xxx put contents here xxx
  29
  30         Version:        xxx put version here xxx
  31
  32         Copyright:      © 1999 by Apple Computer, Inc., all rights reserved.
  33
  34         File Ownership:
  35
  36                 DRI:                            xxx put dri here xxx
  37
  38                 Other Contact:          xxx put other contact here xxx
  39
  40                 Technology:                     xxx put technology here xxx
  41
  42         Writers:
  43
  44                 (BWS)   Brent Schorsch
  45
  46         Change History (most recent first):
  47
  48                  <5>     11/1/99        BWS             [2405720]  We need a better check for 'bit padding' items,
  49                                                                         rather than just is constant. We will check to make sure the
  50                                                                         item is constant, and has no usage, or zero usage. This means we
  51                                                                         need to pass an additional parameter to some internal functions
  52                  <4>      4/7/99        BWS             Add flags to report items (for reverse)
  53                  <3>     3/19/99        BWS             Build stub library
  54                  <2>     3/17/99        BWS             [2314839]  Add flags field to HIDPreparsedData, is set in
  55                                                                         HIDOpenReportDescriptor
  56                  <1>      3/5/99        BWS             first checked in
  57 */
  58
  59 #include "MacTypes.h"
  60 #include <IOKit/hidsystem/IOHIDDescriptorParser.h>
  61
  62 /* the following constants are from the USB HID Specification (www.usb.org)*/
  63
  64 /*------------------------------------------------------------------------------*/
  65 /*                                                                                                                                                              */
  66 /* HID Header                                                                                                                                   */
  67 /*                                                                                                                                                              */
  68 /* ---------------------------------------------------------                                    */
  69 /* |  7   |      6       |      5       |  4   |  3       |      2       |      1       |  0   |                                        */
  70 /* |                    Tag                        |    Type     |        Size     |                                    */
  71 /* ---------------------------------------------------------                                    */
  72 /*------------------------------------------------------------------------------*/
  73 enum {
  74         kHIDItemSizeMask                        = 0x03,
  75         kHIDItemTagMask                         = 0xF0,
  76         kHIDItemTagShift                        = 4,
  77         kHIDItemTypeMask                        = 0x0C,
  78         kHIDItemTypeShift                       = 2,
  79         kHIDLongItemHeader                      = 0xFE
  80 };
  81
  82 /*------------------------------------------------------------------------------*/
  83 /*                                                                                                                                                              */
  84 /* HID Item Type Definitions                                                                                                    */
  85 /*                                                                                                                                                              */
  86 /*------------------------------------------------------------------------------*/
  87 enum {
  88         kHIDTypeMain                            = 0,
  89         kHIDTypeGlobal                          = 1,
  90         kHIDTypeLocal                           = 2,
  91         kHIDTypeLong                            = 3
  92 };
  93
  94 /*------------------------------------------------------------------------------*/
  95 /*                                                                                                                                                              */
  96 /* HID Item Tag Definitions - Main Items                                                                                */
  97 /*                                                                                                                                                              */
  98 /*------------------------------------------------------------------------------*/
  99 enum {
 100         kHIDTagInput                            = 8,
 101         kHIDTagOutput                           = 9,
 102         kHIDTagCollection                       = 0x0A,
 103         kHIDTagFeature                          = 0x0B,
 104         kHIDTagEndCollection            = 0x0C
 105 };
 106
 107 /*------------------------------------------------------------------------------*/
 108 /*                                                                                                                                                              */
 109 /* HID Item Tag Definitions - Globals                                                                                   */
 110 /*                                                                                                                                                              */
 111 /*------------------------------------------------------------------------------*/
 112 enum {
 113         kHIDTagUsagePage                        = 0,
 114         kHIDTagLogicalMinimum           = 1,
 115         kHIDTagLogicalMaximum           = 2,
 116         kHIDTagPhysicalMinimum          = 3,
 117         kHIDTagPhysicalMaximum          = 4,
 118         kHIDTagUnitExponent                     = 5,
 119         kHIDTagUnit                                     = 6,
 120         kHIDTagReportSize                       = 7,
 121         kHIDTagReportID                         = 8,
 122         kHIDTagReportCount                      = 9,
 123         kHIDTagPush                                     = 0x0A,
 124         kHIDTagPop                                      = 0x0B
 125 };
 126
 127 /*------------------------------------------------------------------------------*/
 128 /*                                                                                                                                                              */
 129 /* HID Item Tag Definitions - Locals                                                                                    */
 130 /*                                                                                                                                                              */
 131 /*------------------------------------------------------------------------------*/
 132 enum {
 133         kHIDTagUsage                            = 0,
 134         kHIDTagUsageMinimum                     = 1,
 135         kHIDTagUsageMaximum                     = 2,
 136         kHIDTagDesignatorIndex          = 3,
 137         kHIDTagDesignatorMinimum        = 4,
 138         kHIDTagDesignatorMaximum        = 5,
 139         kHIDTagStringIndex                      = 7,
 140         kHIDTagStringMinimum            = 8,
 141         kHIDTagStringMaximum            = 9,
 142         kHIDTagSetDelimiter                     = 0x0A
 143 };
 144
 145 /*------------------------------------------------------------------------------*/
 146 /*                                                                                                                                                              */
 147 /* HID Main Item Header Bit Definitions                                                                                 */
 148 /*                                                                                                                                                              */
 149 /*------------------------------------------------------------------------------*/
 150 enum {
 151         kHIDDataBufferedBytes           = 0x0100,
 152         kHIDDataVolatileBit                     = 0x80,
 153         kHIDDataVolatile                        = 0x80,
 154         kHIDDataNullStateBit            = 0x40,
 155         kHIDDataNullState                       = 0x40,
 156         kHIDDataNoPreferredBit          = 0x20,
 157         kHIDDataNoPreferred                     = 0x20,
 158         kHIDDataNonlinearBit            = 0x10,
 159         kHIDDataNonlinear                       = 0x10,
 160         kHIDDataWrapBit                         = 0x08,
 161         kHIDDataWrap                            = 0x08,
 162         kHIDDataRelativeBit                     = 0x04,
 163         kHIDDataRelative                        = 0x04,
 164         kHIDDataAbsolute                        = 0x00,
 165         kHIDDataVariableBit                     = 0x02,
 166         kHIDDataVariable                        = 0x02,
 167         kHIDDataArrayBit                        = 0x02,
 168         kHIDDataArray                           = 0x00,
 169         kHIDDataConstantBit                     = 0x01,
 170         kHIDDataConstant                        = 0x01
 171 };
 172
 173 /*------------------------------------------------------------------------------*/
 174 /*                                                                                                                                                              */
 175 /* HID Collection Data Definitions                                                                                              */
 176 /*                                                                                                                                                              */
 177 /*------------------------------------------------------------------------------*/
 178 enum {
 179         kHIDPhysicalCollection          = 0x00,
 180         kHIDApplicationCollection       = 0x01
 181 };
 182
 183 /*------------------------------------------------------------------------------*/
 184 /*                                                                                                                                                              */
 185 /* HIDLibrary private defs                                                                                                              */
 186 /*                                                                                                                                                              */
 187 /*------------------------------------------------------------------------------*/
 188
 189 enum
 190 {
 191         kHIDOSType                      =       'hid '
 192 };
 193
 194 struct HIDItem
 195 {
 196         ByteCount       byteCount;
 197         SInt32          itemType;
 198         SInt32          tag;
 199         SInt32          signedValue;
 200         UInt32          unsignedValue;
 201 };
 202 typedef struct HIDItem HIDItem;
 203
 204 struct HIDGlobalItems
 205 {
 206         HIDUsage        usagePage;
 207         SInt32          logicalMinimum;
 208         SInt32          logicalMaximum;
 209         SInt32          physicalMinimum;
 210         SInt32          physicalMaximum;
 211         SInt32          unitExponent;
 212         SInt32          units;
 213         ByteCount       reportSize;
 214         SInt32          reportID;
 215         SInt32          reportCount;
 216         SInt32          reportIndex;
 217 };
 218 typedef struct HIDGlobalItems HIDGlobalItems;
 219
 220 struct HIDReportSizes
 221 {
 222         SInt32          reportID;
 223         SInt32          inputBitCount;
 224         SInt32          outputBitCount;
 225         SInt32          featureBitCount;
 226 };
 227 typedef struct HIDReportSizes HIDReportSizes;
 228
 229 struct HIDCollection
 230 {
 231         SInt32          data;
 232         SInt32          usagePage;
 233         SInt32          firstUsageItem;
 234         SInt32          usageItemCount;
 235         SInt32          firstReportItem;
 236         SInt32          reportItemCount;
 237         SInt32          parent;
 238         SInt32          children;
 239         SInt32          firstChild;
 240         SInt32          nextSibling;
 241 };
 242 typedef struct HIDCollection HIDCollection;
 243
 244 enum
 245 {
 246         kHIDReportItemFlag_Reversed                     =       0x00000001
 247 };
 248
 249 struct HIDReportItem
 250 {
 251         UInt32                          reportType;
 252         HIDGlobalItems          globals;
 253         SInt32                          startBit;
 254         SInt32                          parent;
 255         SInt32                          dataModes;
 256         SInt32                          firstUsageItem;
 257         SInt32                          usageItemCount;
 258         SInt32                          firstStringItem;
 259         SInt32                          stringItemCount;
 260         SInt32                          firstDesigItem;
 261         SInt32                          desigItemCount;
 262         UInt32                          flags;
 263 };
 264 typedef struct HIDReportItem HIDReportItem;
 265
 266 struct HIDP_UsageItem
 267 {
 268         Boolean         isRange;
 269         Boolean         reserved;
 270         HIDUsage        usagePage;
 271         HIDUsage        usage;
 272         SInt32          usageMinimum;
 273         SInt32          usageMaximum;
 274 };
 275 typedef struct HIDP_UsageItem HIDP_UsageItem;
 276
 277 struct HIDStringItem
 278 {
 279         Boolean         isRange;
 280         Boolean         reserved;
 281         SInt32          index;
 282         SInt32          minimum;
 283         SInt32          maximum;
 284 };
 285 typedef struct HIDStringItem HIDStringItem;
 286 typedef HIDStringItem HIDDesignatorItem;
 287
 288 struct HIDPreparsedData
 289 {
 290         OSType                          hidTypeIfValid;
 291         HIDCollection *         collections;
 292         UInt32                          collectionCount;
 293         HIDReportItem *         reportItems;
 294         UInt32                          reportItemCount;
 295         HIDReportSizes *        reports;
 296         UInt32                          reportCount;
 297         HIDP_UsageItem *        usageItems;
 298         UInt32                          usageItemCount;
 299         HIDStringItem *         stringItems;
 300         UInt32                          stringItemCount;
 301         HIDDesignatorItem * desigItems;
 302         UInt32                          desigItemCount;
 303         UInt8 *                         rawMemPtr;
 304         UInt32                          flags;
 305         ByteCount                       numBytesAllocated;
 306 };
 307 typedef struct HIDPreparsedData HIDPreparsedData;
 308 typedef HIDPreparsedData * HIDPreparsedDataPtr;
 309
 310 extern
 311 OSStatus
 312 HIDCheckReport                     (HIDReportType                       reportType,
 313                                                         HIDPreparsedDataRef             preparsedDataRef,
 314                                                         HIDReportItem *                 reportItem,
 315                                                         void *                                  report,
 316                                                         ByteCount                               reportLength);
 317
 318
 319 extern
 320 OSStatus
 321 HIDGetData                                 (void *                                      report,
 322                                                         ByteCount                               reportLength,
 323                                                         UInt32                                  start,
 324                                                         UInt32                                  size,
 325                                                         SInt32 *                                value,
 326                                                         Boolean                                 signExtend);
 327
 328 extern
 329 OSStatus
 330 HIDPostProcessRIValue      (HIDReportItem *                     reportItem,
 331                                                         SInt32 *                                value);
 332
 333 extern
 334 OSStatus
 335 HIDPreProcessRIValue       (HIDReportItem *                     reportItem,
 336                                                         SInt32 *                                value);
 337
 338 extern
 339 Boolean
 340 HIDHasUsage                                (HIDPreparsedDataRef         preparsedDataRef,
 341                                                         HIDReportItem *                 reportItem,
 342                                                         HIDUsage                                usagePage,
 343                                                         HIDUsage                                usage,
 344                                                         UInt32 *                                usageIndex,
 345                                                         UInt32 *                                count);
 346
 347 extern
 348 Boolean
 349 HIDIsButton                                (HIDReportItem *                     reportItem,
 350                                                         HIDPreparsedDataRef             preparsedDataRef);
 351
 352 extern
 353 Boolean
 354 HIDIsVariable                      (HIDReportItem *                     reportItem,
 355                                                         HIDPreparsedDataRef             preparsedDataRef);
 356
 357 extern
 358 OSStatus
 359 HIDPutData                                 (void *                                      report,
 360                                                         ByteCount                               reportLength,
 361                                                         UInt32                                  start,
 362                                                         UInt32                                  size,
 363                                                         SInt32                                  value);
 364
 365 extern
 366 OSStatus
 367 HIDScaleUsageValueIn       (HIDReportItem *                     reportItem,
 368                                                         UInt32                                  value,
 369                                                         SInt32 *                                scaledValue);
 370
 371 extern
 372 OSStatus
 373 HIDScaleUsageValueOut      (HIDReportItem *                     reportItem,
 374                                                         UInt32                                  value,
 375                                                         SInt32 *                                scaledValue);
 376
 377 extern
 378 void
 379 HIDUsageAndPageFromIndex   (HIDPreparsedDataRef         preparsedDataRef,
 380                                                         HIDReportItem *                 reportItem,
 381                                                         UInt32                                  index,
 382                                                         HIDUsageAndPage *               usageAndPage);
 383
 384 extern
 385 Boolean
 386 HIDUsageInRange                    (HIDP_UsageItem *            usageItem,
 387                                                         HIDUsage                                usagePage,
 388                                                         HIDUsage                                usage);
 389
 390 #endif