git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Demo/FreeRTOS_Plus_UDP_and_CLI_LPC1830_GCC/ThirdParty/LPCOpen/LPCUSBLib/Drivers/USB/Class/Device/HIDClassDevice.h

   1 /*\r
   2  * @brief Device mode driver for the library USB HID Class driver\r
   3  *\r
   4  * @note\r
   5  * Copyright(C) NXP Semiconductors, 2012\r
   6  * Copyright(C) Dean Camera, 2011, 2012\r
   7  * All rights reserved.\r
   8  *\r
   9  * @par\r
  10  * Software that is described herein is for illustrative purposes only\r
  11  * which provides customers with programming information regarding the\r
  12  * LPC products.  This software is supplied "AS IS" without any warranties of\r
  13  * any kind, and NXP Semiconductors and its licensor disclaim any and\r
  14  * all warranties, express or implied, including all implied warranties of\r
  15  * merchantability, fitness for a particular purpose and non-infringement of\r
  16  * intellectual property rights.  NXP Semiconductors assumes no responsibility\r
  17  * or liability for the use of the software, conveys no license or rights under any\r
  18  * patent, copyright, mask work right, or any other intellectual property rights in\r
  19  * or to any products. NXP Semiconductors reserves the right to make changes\r
  20  * in the software without notification. NXP Semiconductors also makes no\r
  21  * representation or warranty that such application will be suitable for the\r
  22  * specified use without further testing or modification.\r
  23  *\r
  24  * @par\r
  25  * Permission to use, copy, modify, and distribute this software and its\r
  26  * documentation is hereby granted, under NXP Semiconductors' and its\r
  27  * licensor's relevant copyrights in the software, without fee, provided that it\r
  28  * is used in conjunction with NXP Semiconductors microcontrollers.  This\r
  29  * copyright, permission, and disclaimer notice must appear in all copies of\r
  30  * this code.\r
  31  */\r
  32 \r
  33 /** @ingroup Group_USBClassHID\r
  34  *  @defgroup Group_USBClassHIDDevice HID Class Device Mode Driver\r
  35  *\r
  36  *  @section Sec_Dependencies Module Source Dependencies\r
  37  *  The following files must be built with any user project that uses this module:\r
  38  *    - nxpUSBlib/Drivers/USB/Class/Device/HID.c <i>(Makefile source module name: NXPUSBLIB_SRC_USBCLASS)</i>\r
  39  *\r
  40  *  @section Sec_ModDescription Module Description\r
  41  *  Device Mode USB Class driver framework interface, for the HID USB Class driver.\r
  42  *\r
  43  * @{\r
  44  */\r
  45 \r
  46 #ifndef _HID_CLASS_DEVICE_H_\r
  47 #define _HID_CLASS_DEVICE_H_\r
  48 \r
  49 /* Includes: */\r
  50                 #include "../../USB.h"\r
  51                 #include "../Common/HIDClassCommon.h"\r
  52 \r
  53 /* Enable C linkage for C++ Compilers: */\r
  54                 #if defined(__cplusplus)\r
  55 extern "C" {\r
  56                 #endif\r
  57 \r
  58 /* Preprocessor Checks: */\r
  59                 #if !defined(__INCLUDE_FROM_HID_DRIVER)\r
  60                         #error Do not include this file directly. Include LPCUSBlib/Drivers/USB.h instead.\r
  61                 #endif\r
  62 \r
  63 /* Public Interface - May be used in end-application: */\r
  64 /* Type Defines: */\r
  65 /** @brief HID Class Device Mode Configuration and State Structure.\r
  66  *\r
  67  *  Class state structure. An instance of this structure should be made for each HID interface\r
  68  *  within the user application, and passed to each of the HID class driver functions as the\r
  69  *  \c HIDInterfaceInfo parameter. This stores each HID interface's configuration and state information.\r
  70  *\r
  71  * @note Due to technical limitations, the HID device class driver does not utilize a separate OUT\r
  72  *        endpoint for host->device communications. Instead, the host->device data (if any) is sent to\r
  73  *        the device via the control endpoint.\r
  74  */\r
  75 typedef struct {\r
  76         const struct {\r
  77                 uint8_t  InterfaceNumber;                               /**< Interface number of the HID interface within the device. */\r
  78 \r
  79                 uint8_t  ReportINEndpointNumber;                        /**< Endpoint number of the HID interface's IN report endpoint. */\r
  80                 uint16_t ReportINEndpointSize;                          /**< Size in bytes of the HID interface's IN report endpoint. */\r
  81                 bool     ReportINEndpointDoubleBank;                    /**< Indicates if the HID interface's IN report endpoint should use double banking. */\r
  82 \r
  83                 void *PrevReportINBuffer;                               /**< Pointer to a buffer where the previously created HID input report can be\r
  84                                                                                                  *  stored by the driver, for comparison purposes to detect report changes that\r
  85                                                                                                  *  must be sent immediately to the host. This should point to a buffer big enough\r
  86                                                                                                  *  to hold the largest HID input report sent from the HID interface. If this is set\r
  87                                                                                                  *  to \c NULL, it is up to the user to force transfers when needed in the\r
  88                                                                                                  *  @ref CALLBACK_HID_Device_CreateHIDReport() callback function.\r
  89                                                                                                  *\r
  90                                                                                                  * @note Due to the single buffer, the internal driver can only correctly compare\r
  91                                                                                                  *        subsequent reports with identical report IDs. In multiple report devices,\r
  92                                                                                                  *        this buffer should be set to \c NULL and the decision to send reports made\r
  93                                                                                                  *        by the user application instead.\r
  94                                                                                                  */\r
  95                 uint8_t  PrevReportINBufferSize;                        /**< Size in bytes of the given input report buffer. This is used to create a\r
  96                                                                                                          *  second buffer of the same size within the driver so that subsequent reports\r
  97                                                                                                          *  can be compared. If the user app is to determine when reports are to be sent\r
  98                                                                                                          *  exclusively (i.e. @ref PrevReportINBuffer is \c NULL) this value must still be\r
  99                                                                                                          *  set to the size of the largest report the device can issue to the host.\r
 100                                                                                                          */\r
 101                 uint8_t  PortNumber;                            /**< Port number that this interface is running.*/\r
 102         } Config;                               /**< Config data for the USB class interface within the device. All elements in this section\r
 103                                                          *   <b>must</b> be set or the interface will fail to enumerate and operate correctly.\r
 104                                                          */\r
 105 \r
 106         struct {\r
 107                 bool     UsingReportProtocol;                           /**< Indicates if the HID interface is set to Boot or Report protocol mode. */\r
 108                 uint16_t IdleCount;                             /**< Report idle period, in milliseconds, set by the host. */\r
 109                 uint16_t IdleMSRemaining;                               /**< Total number of milliseconds remaining before the idle period elapsed - this\r
 110                                                                                                  *   should be decremented by the user application if non-zero each millisecond. */\r
 111         } State;                        /**< State data for the USB class interface within the device. All elements in this section\r
 112                                                  *   are reset to their defaults when the interface is enumerated.\r
 113                                                  */\r
 114 \r
 115 } USB_ClassInfo_HID_Device_t;\r
 116 \r
 117 /* Function Prototypes: */\r
 118 /**\r
 119  * @brief        Configures the endpoints of a given HID interface, ready for use. This should be linked to the library\r
 120  *  @ref EVENT_USB_Device_ConfigurationChanged() event so that the endpoints are configured when the configuration\r
 121  *  containing the given HID interface is selected.\r
 122  *\r
 123  * @param       HIDInterfaceInfo        : Pointer to a structure containing a HID Class configuration and state.\r
 124  *\r
 125  * @return      Boolean \c true if the endpoints were successfully configured, \c false otherwise.\r
 126  */\r
 127 bool HID_Device_ConfigureEndpoints(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 128 \r
 129 /**\r
 130  * @brief        Processes incoming control requests from the host, that are directed to the given HID class interface. This should be\r
 131  *  linked to the library @ref EVENT_USB_Device_ControlRequest() event.\r
 132  *\r
 133  * @param       HIDInterfaceInfo        : Pointer to a structure containing a HID Class configuration and state.\r
 134  * @return      Nothing\r
 135  */\r
 136 void HID_Device_ProcessControlRequest(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 137 \r
 138 /**\r
 139  * @brief        General management task for a given HID class interface, required for the correct operation of the interface. This should\r
 140  *  be called frequently in the main program loop, before the master USB management task @ref USB_USBTask().\r
 141  *\r
 142  * @param       HIDInterfaceInfo        : Pointer to a structure containing a HID Class configuration and state.\r
 143  * @return      Nothing\r
 144  */\r
 145 void HID_Device_USBTask(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 146 \r
 147 /**\r
 148  * @brief        HID class driver callback for the user creation of a HID IN report. This callback may fire in response to either\r
 149  *  HID class control requests from the host, or by the normal HID endpoint polling procedure. Inside this callback the\r
 150  *  user is responsible for the creation of the next HID input report to be sent to the host.\r
 151  *\r
 152  * @param       HIDInterfaceInfo        : Pointer to a structure containing a HID Class configuration and state.\r
 153  * @param       ReportID        : If preset to a non-zero value, this is the report ID being requested by the host. If zero,\r
 154  *                                   this should be set to the report ID of the generated HID input report (if any). If multiple\r
 155  *                                   reports are not sent via the given HID interface, this parameter should be ignored.\r
 156  * @param       ReportType      : Type of HID report to generate, either @ref HID_REPORT_ITEM_In or @ref HID_REPORT_ITEM_Feature.\r
 157  * @param       ReportData      : Pointer to a buffer where the generated HID report should be stored.\r
 158  * @param       ReportSize      : Number of bytes in the generated input report, or zero if no report is to be sent.\r
 159  *\r
 160  * @return      Boolean \c true to force the sending of the report even if it is identical to the previous report and still within\r
 161  *          the idle period (useful for devices which report relative movement), \c false otherwise.\r
 162  */\r
 163 bool CALLBACK_HID_Device_CreateHIDReport(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo,\r
 164                                                                                  uint8_t *const ReportID,\r
 165                                                                                  const uint8_t ReportType,\r
 166                                                                                  void *ReportData,\r
 167                                                                                  uint16_t *const ReportSize) ATTR_NON_NULL_PTR_ARG(1)\r
 168 ATTR_NON_NULL_PTR_ARG(2) ATTR_NON_NULL_PTR_ARG(4) ATTR_NON_NULL_PTR_ARG(5);\r
 169 \r
 170 /**\r
 171  * @brief        HID class driver callback for the user processing of a received HID OUT report. This callback may fire in response to\r
 172  *  either HID class control requests from the host, or by the normal HID endpoint polling procedure. Inside this callback\r
 173  *  the user is responsible for the processing of the received HID output report from the host.\r
 174  *\r
 175  * @param       HIDInterfaceInfo        : Pointer to a structure containing a HID Class configuration and state.\r
 176  * @param       ReportID        : Report ID of the received output report. If multiple reports are not received via the given HID\r
 177  *                                   interface, this parameter should be ignored.\r
 178  * @param       ReportType      : Type of received HID report, either @ref HID_REPORT_ITEM_Out or @ref HID_REPORT_ITEM_Feature.\r
 179  * @param       ReportData      : Pointer to a buffer where the received HID report is stored.\r
 180  * @param       ReportSize      : Size in bytes of the received report from the host.\r
 181  * @return      Nothing\r
 182  */\r
 183 void CALLBACK_HID_Device_ProcessHIDReport(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo,\r
 184                                                                                   const uint8_t ReportID,\r
 185                                                                                   const uint8_t ReportType,\r
 186                                                                                   const void *ReportData,\r
 187                                                                                   const uint16_t ReportSize) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(4);\r
 188 \r
 189 /* Inline Functions: */\r
 190 /**\r
 191  * @brief        Indicates that a millisecond of idle time has elapsed on the given HID interface, and the interface's idle count should be\r
 192  *  decremented. This should be called once per millisecond so that hardware key-repeats function correctly. It is recommended\r
 193  *  that this be called by the @ref EVENT_USB_Device_StartOfFrame() event, once SOF events have been enabled via\r
 194  *  @ref USB_Device_EnableSOFEvents().\r
 195  *\r
 196  * @param       HIDInterfaceInfo        : Pointer to a structure containing a HID Class configuration and state.\r
 197  */\r
 198 PRAGMA_ALWAYS_INLINE\r
 199 static inline void HID_Device_MillisecondElapsed(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo) ATTR_ALWAYS_INLINE\r
 200 ATTR_NON_NULL_PTR_ARG(1);\r
 201 static inline void HID_Device_MillisecondElapsed(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo)\r
 202 {\r
 203         if (HIDInterfaceInfo->State.IdleMSRemaining) {\r
 204                 HIDInterfaceInfo->State.IdleMSRemaining--;\r
 205         }\r
 206 }\r
 207 \r
 208 /* Disable C linkage for C++ Compilers: */\r
 209                 #if defined(__cplusplus)\r
 210 }\r
 211                 #endif\r
 212 \r
 213 #endif\r
 214 \r
 215 /** @} */\r
 216 \r