SAMV71 Xplained Ultra Software Package 1.5

HIDReports.h

Go to the documentation of this file.
00001 /* ---------------------------------------------------------------------------- */
00002 /*                  Atmel Microcontroller Software Support                      */
00003 /*                       SAM Software Package License                           */
00004 /* ---------------------------------------------------------------------------- */
00005 /* Copyright (c) 2015, Atmel Corporation                                        */
00006 /*                                                                              */
00007 /* All rights reserved.                                                         */
00008 /*                                                                              */
00009 /* Redistribution and use in source and binary forms, with or without           */
00010 /* modification, are permitted provided that the following condition is met:    */
00011 /*                                                                              */
00012 /* - Redistributions of source code must retain the above copyright notice,     */
00013 /* this list of conditions and the disclaimer below.                            */
00014 /*                                                                              */
00015 /* Atmel's name may not be used to endorse or promote products derived from     */
00016 /* this software without specific prior written permission.                     */
00017 /*                                                                              */
00018 /* DISCLAIMER:  THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR   */
00019 /* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF */
00020 /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE   */
00021 /* DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,      */
00022 /* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT */
00023 /* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,  */
00024 /* OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF    */
00025 /* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING         */
00026 /* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, */
00027 /* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                           */
00028 /* ---------------------------------------------------------------------------- */
00029 
00030 /**\file
00031  *
00032  * \section Purpose
00033  *
00034  * Definitions used when declaring an HID report descriptors.
00035  *
00036  * \section Usage
00037  *
00038  * Use the definitions provided here when declaring a report descriptor,
00039  * which shall be an uint8_t array.
00040 */
00041 
00042 #ifndef _HIDREPORTS_H_
00043 #define _HIDREPORTS_H_
00044 /** \addtogroup usb_hid
00045  *@{
00046  *  \addtogroup usb_hid_report USB HID Report
00047  *  @{
00048  */
00049 
00050 /*----------------------------------------------------------------------------
00051  *         Headers
00052  *----------------------------------------------------------------------------*/
00053 
00054 #include <stdint.h>
00055 
00056 /*----------------------------------------------------------------------------
00057  *         Definitions
00058  *----------------------------------------------------------------------------*/
00059 
00060 /** \addtogroup usb_hid_item HID Items Definitions
00061  *      @{
00062  */
00063 /** Item size 0 bytes */
00064 #define HIDItemSize_0B                          0
00065 /** Item size 1 bytes */
00066 #define HIDItemSize_1B                          1
00067 /** Item size 2 bytes */
00068 #define HIDItemSize_2B                          2
00069 /** Item size 4 bytes */
00070 #define HIDItemSize_4B                          3
00071 
00072 /** Item type: Main */
00073 #define HIDItemType_MAIN                        0
00074 /** Item type: Global */
00075 #define HIDItemType_GLOBAL                      1
00076 /** Item type: Local */
00077 #define HIDItemType_LOCAL                       2
00078 
00079 /** Item prefix for long items */
00080 #define HIDItem_LONGITEM                        0xFE
00081 /**     @}*/
00082 
00083 /** \addtogroup usb_hid_main HID Main Item Tags
00084  *      @{
00085  * This section lists the Main Item Tags defined for HID device.
00086  * ( HID Spec. 6.2.2.4 )
00087  *
00088  * - \ref HIDReport_INPUT
00089  * - \ref HIDReport_FEATURE
00090  * - \ref HIDReport_COLLECTION
00091  * - \ref HIDReport_ENDCOLLECTION
00092  */
00093 /** Input item. */
00094 #define HIDReport_INPUT                         0x80
00095 /** Output item. */
00096 #define HIDReport_OUTPUT                        0x90
00097 /** Feature item. */
00098 #define HIDReport_FEATURE                       0xB0
00099 /** Collection item. */
00100 #define HIDReport_COLLECTION                    0xA0
00101 /** End of collection item. */
00102 #define HIDReport_ENDCOLLECTION                 0xC0
00103 /**     @}*/
00104 
00105 /** \addtogroup usb_hid_data HID Items for Data Fields
00106  *      @{
00107  * This section lists definitions for HID Input, Output and Feature items that
00108  * are used to create the data fields within a report.
00109  * ( HID Spec. 6.2.2.5 )
00110  * - \ref HIDReport_CONSTANT
00111  * - \ref HIDReport_VARIABLE
00112  * - \ref HIDReport_RELATIVE
00113  * - \ref HIDReport_WRAP
00114  * - \ref HIDReport_NONLINEAR
00115  * - \ref HIDReport_NOPREFERRED
00116  * - \ref HIDReport_NULLSTATE
00117  * - \ref HIDReport_VOLATILE
00118  * - \ref HIDReport_BUFFEREDBYTES
00119  */
00120 /** The report value is constant (vs. variable). */
00121 #define HIDReport_CONSTANT                      (1 << 0)
00122 /** Data reported is a variable (vs. array). */
00123 #define HIDReport_VARIABLE                      (1 << 1)
00124 /** Data is relative (vs. absolute). */
00125 #define HIDReport_RELATIVE                      (1 << 2)
00126 /** Value rolls over when it reach a maximum/minimum. */
00127 #define HIDReport_WRAP                          (1 << 3)
00128 /** Indicates that the data reported has been processed and is no longer */
00129 /** linear with the original measurements. */
00130 #define HIDReport_NONLINEAR                     (1 << 4)
00131 /** Device has no preferred state to which it automatically returns. */
00132 #define HIDReport_NOPREFERRED                   (1 << 5)
00133 /** Device has a null state, in which it does not report meaningful */
00134 /** information. */
00135 #define HIDReport_NULLSTATE                     (1 << 6)
00136 /** Indicates data can change without the host intervention. */
00137 #define HIDReport_VOLATILE                      (1 << 7)
00138 /** Indicates the device produces a fixed-length stream of bytes. */
00139 #define HIDReport_BUFFEREDBYTES                 (1 << 8)
00140 /**     @}*/
00141 
00142 /** \addtogroup usb_hid_collection HID Collection Items
00143  *      @{
00144  * This section lists definitions for HID Collection Items.
00145  * ( HID Spec. 6.2.2.6 )
00146  * - \ref HIDReport_COLLECTION_PHYSICAL
00147  * - \ref HIDReport_COLLECTION_APPLICATION
00148  * - \ref HIDReport_COLLECTION_LOGICAL
00149  * - \ref HIDReport_COLLECTION_REPORT
00150  * - \ref HIDReport_COLLECTION_NAMEDARRAY
00151  * - \ref HIDReport_COLLECTION_USAGESWITCH
00152  * - \ref HIDReport_COLLECTION_USAGEMODIFIER
00153  */
00154 /** Physical collection. */
00155 #define HIDReport_COLLECTION_PHYSICAL           0x00
00156 /** Application collection. */
00157 #define HIDReport_COLLECTION_APPLICATION        0x01
00158 /** Logical collection. */
00159 #define HIDReport_COLLECTION_LOGICAL            0x02
00160 /** Report collection. */
00161 #define HIDReport_COLLECTION_REPORT             0x03
00162 /** Named array collection. */
00163 #define HIDReport_COLLECTION_NAMEDARRAY         0x04
00164 /** Usage switch collection. */
00165 #define HIDReport_COLLECTION_USAGESWITCH        0x05
00166 /** Usage modifier collection */
00167 #define HIDReport_COLLECTION_USAGEMODIFIER      0x06
00168 /**     @}*/
00169 
00170 /** \addtogroup usb_hid_global HID Global Items
00171  *      @{
00172  * This section lists HID Global Items.
00173  * ( HID Spec. 6.2.2.7 )
00174  * - \ref HIDReport_GLOBAL_USAGEPAGE
00175  * - \ref HIDReport_GLOBAL_LOGICALMINIMUM
00176  * - \ref HIDReport_GLOBAL_LOGICALMAXIMUM
00177  * - \ref HIDReport_GLOBAL_PHYSICALMINIMUM
00178  * - \ref HIDReport_GLOBAL_PHYSICALMAXIMUM
00179  * - \ref HIDReport_GLOBAL_UNITEXPONENT
00180  * - \ref HIDReport_GLOBAL_UNIT
00181  * - \ref HIDReport_GLOBAL_REPORTSIZE
00182  * - \ref HIDReport_GLOBAL_REPORTID
00183  * - \ref HIDReport_GLOBAL_REPORTCOUNT
00184  * - \ref HIDReport_GLOBAL_PUSH
00185  * - \ref HIDReport_GLOBAL_POP
00186  */
00187 /** Current usage page. */
00188 #define HIDReport_GLOBAL_USAGEPAGE              0x04
00189 /** Minimum value that a variable or array item will report. */
00190 #define HIDReport_GLOBAL_LOGICALMINIMUM         0x14
00191 /** Maximum value that a variable or array item will report. */
00192 #define HIDReport_GLOBAL_LOGICALMAXIMUM         0x24
00193 /** Minimum value for the physical extent of a variable item. */
00194 #define HIDReport_GLOBAL_PHYSICALMINIMUM        0x34
00195 /** Maximum value for the physical extent of a variable item. */
00196 #define HIDReport_GLOBAL_PHYSICALMAXIMUM        0x44
00197 /** Value of the unit exponent in base 10. */
00198 #define HIDReport_GLOBAL_UNITEXPONENT           0x54
00199 /** Unit values. */
00200 #define HIDReport_GLOBAL_UNIT                   0x64
00201 /** Size of the report fields in bits. */
00202 #define HIDReport_GLOBAL_REPORTSIZE             0x74
00203 /** Specifies the report ID. */
00204 #define HIDReport_GLOBAL_REPORTID               0x84
00205 /** Number of data fields for an item. */
00206 #define HIDReport_GLOBAL_REPORTCOUNT            0x94
00207 /** Places a copy of the global item state table on the stack. */
00208 #define HIDReport_GLOBAL_PUSH                   0xA4
00209 /** Replaces the item state table with the top structure from the stack. */
00210 #define HIDReport_GLOBAL_POP                    0xB4
00211 /**     @}*/
00212 
00213 /** \addtogroup usb_hid_local HID Local Items
00214  *      @{
00215  * This section lists definitions for HID Local Items.
00216  * ( HID Spec. 6.2.2.8 )
00217  * - \ref HIDReport_LOCAL_USAGE
00218  * - \ref HIDReport_LOCAL_USAGEMINIMUM
00219  * - \ref HIDReport_LOCAL_USAGEMAXIMUM
00220  * - \ref HIDReport_LOCAL_DESIGNATORINDEX
00221  * - \ref HIDReport_LOCAL_DESIGNATORMINIMUM
00222  * - \ref HIDReport_LOCAL_DESIGNATORMAXIMUM
00223  * - \ref HIDReport_LOCAL_STRINGINDEX
00224  * - \ref HIDReport_LOCAL_STRINGMINIMUM
00225  * - \ref HIDReport_LOCAL_STRINGMAXIMUM
00226  * - \ref HIDReport_LOCAL_DELIMITER
00227  */
00228 /** Suggested usage for an item or collection. */
00229 #define HIDReport_LOCAL_USAGE                   0x08
00230 /** Defines the starting usage associated with an array or bitmap. */
00231 #define HIDReport_LOCAL_USAGEMINIMUM            0x18
00232 /** Defines the ending usage associated with an array or bitmap. */
00233 #define HIDReport_LOCAL_USAGEMAXIMUM            0x28
00234 /** Determines the body part used for a control. */
00235 #define HIDReport_LOCAL_DESIGNATORINDEX         0x38
00236 /** Defines the index of the starting designator associated with an array or */
00237 /** bitmap. */
00238 #define HIDReport_LOCAL_DESIGNATORMINIMUM       0x48
00239 /** Defines the index of the ending designator associated with an array or */
00240 /** bitmap. */
00241 #define HIDReport_LOCAL_DESIGNATORMAXIMUM       0x58
00242 /** String index for a string descriptor. */
00243 #define HIDReport_LOCAL_STRINGINDEX             0x78
00244 /** Specifies the first string index when assigning a group of sequential */
00245 /** strings to controls in an array or bitmap. */
00246 #define HIDReport_LOCAL_STRINGMINIMUM           0x88
00247 /** Specifies the last string index when assigning a group of sequential */
00248 /** strings to controls in an array or bitmap. */
00249 #define HIDReport_LOCAL_STRINGMAXIMUM           0x98
00250 /** Defines the beginning or end of a set of local items. */
00251 #define HIDReport_LOCAL_DELIMITER               0xA8
00252 /**     @}*/
00253 
00254 /*----------------------------------------------------------------------------
00255  *         Types
00256  *----------------------------------------------------------------------------*/
00257 
00258 #pragma pack(1)
00259 #if defined   ( __CC_ARM   ) /* Keil ¦̀Vision 4 */
00260 #elif defined ( __ICCARM__ ) /* IAR Ewarm 5.41+ */
00261 #define __attribute__(...)
00262 #elif defined (  __GNUC__  ) /* GCC CS3 2009q3-68 */
00263 #endif
00264 
00265 /** HID Short Item Header, followed by bSize bytes of data */
00266 typedef struct _HIDShortItem {
00267     uint8_t bSize:2,    /**< data size (0, 1, 2 or 4) */
00268             bType:2,    /**< fundamental type */
00269             bTag:4;     /**< item type */
00270 } HIDShortItem;
00271 
00272 /** HID Long Item Header, followed by bDataSize bytes of data */
00273 typedef struct _HIDLongItem {
00274     uint8_t  bPrefix;       /**< Prefix, 0xFE */
00275     uint8_t  bDataSize;     /**< data size */
00276     uint16_t bLongItemTag;  /**< item type */
00277 } HIDLongItem;
00278 
00279 /** HID Report without ID (with one byte data) */
00280 typedef struct _HIDReportNoID {
00281     uint8_t  bData[1];      /**< First report data byte */
00282 } HIDReportNoID;
00283 
00284 /** HID Report with ID (with one byte data) */
00285 typedef struct _HIDReport {
00286     uint8_t  bID;           /**< Report ID */
00287     uint8_t  bData[1];      /**< First report data byte */
00288 } HIDReport;
00289 
00290 #pragma pack()
00291 
00292 /*----------------------------------------------------------------------------
00293  *         Functions
00294  *----------------------------------------------------------------------------*/
00295 
00296 /** @}*/
00297 /**@}*/
00298 #endif /*#ifndef _HIDREPORTS_H_ */
00299 
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines