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

   1 /*\r
   2  * @brief Host 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_USBClassHIDHost HID Class Host 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  *    - LPCUSBlib/Drivers/USB/Class/Host/HID.c <i>(Makefile source module name: LPCUSBlib_SRC_USBCLASS)</i>\r
  39  *\r
  40  *  @section Sec_ModDescription Module Description\r
  41  *  Host 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_HOST_H__\r
  47 #define __HID_CLASS_HOST_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                 /* Macros: */\r
  65                         /** Error code for some HID Host functions, indicating a logical (and not hardware) error. */\r
  66                         #define HID_ERROR_LOGICAL              0x80\r
  67 \r
  68                 /* Type Defines: */\r
  69                         /** @brief HID Class Host Mode Configuration and State Structure.\r
  70                          *\r
  71                          *  Class state structure. An instance of this structure should be made within the user application,\r
  72                          *  and passed to each of the HID class driver functions as the \c HIDInterfaceInfo parameter. This\r
  73                          *  stores each HID interface's configuration and state information.\r
  74                          */\r
  75                         typedef struct\r
  76                         {\r
  77                                 struct\r
  78                                 {\r
  79                                         uint8_t  DataINPipeNumber; /**< Pipe number of the HID interface's IN data pipe. */\r
  80                                         bool     DataINPipeDoubleBank; /**< Indicates if the HID interface's IN data pipe should use double banking. */\r
  81 \r
  82                                         uint8_t  DataOUTPipeNumber; /**< Pipe number of the HID interface's OUT data pipe. */\r
  83                                         bool     DataOUTPipeDoubleBank; /**< Indicates if the HID interface's OUT data pipe should use double banking. */\r
  84 \r
  85                                         uint8_t  HIDInterfaceProtocol; /**< HID interface protocol value to match against if a specific\r
  86                                                                         *   boot subclass protocol is required, a protocol value from the\r
  87                                                                         *   @ref HID_Descriptor_ClassSubclassProtocol_t enum.\r
  88                                                                         */\r
  89                                         #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)\r
  90                                         HID_ReportInfo_t* HIDParserData; /**< HID parser data to store the parsed HID report data, when boot protocol\r
  91                                                                           *   is not used.\r
  92                                                                                                           *\r
  93                                                                           *  @note When the \c HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined,\r
  94                                                                           *        this method is unavailable.\r
  95                                                                           */\r
  96                                         #endif\r
  97 \r
  98                                         uint8_t  PortNumber;            /**< Port number that this interface is running.\r
  99                                                                                                 */\r
 100                                 } Config; /**< Config data for the USB class interface within the device. All elements in this section\r
 101                                            *   <b>must</b> be set or the interface will fail to enumerate and operate correctly.\r
 102                                            */\r
 103                                 struct\r
 104                                 {\r
 105                                         bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid\r
 106                                                         *   after @ref HID_Host_ConfigurePipes() is called and the Host state machine is in the\r
 107                                                         *   Configured state.\r
 108                                                         */\r
 109                                         uint8_t InterfaceNumber; /**< Interface index of the HID interface within the attached device. */\r
 110 \r
 111                                         uint16_t DataINPipeSize; /**< Size in bytes of the HID interface's IN data pipe. */\r
 112                                         uint16_t DataOUTPipeSize;  /**< Size in bytes of the HID interface's OUT data pipe. */\r
 113 \r
 114                                         bool SupportsBootProtocol; /**< Indicates if the current interface instance supports the HID Boot\r
 115                                                                     *   Protocol when enabled via @ref HID_Host_SetBootProtocol().\r
 116                                                                     */\r
 117                                         bool DeviceUsesOUTPipe; /**< Indicates if the current interface instance uses a separate OUT data pipe for\r
 118                                                                  *   OUT reports, or if OUT reports are sent via the control pipe instead.\r
 119                                                                  */\r
 120                                         bool UsingBootProtocol; /**< Indicates that the interface is currently initialized in Boot Protocol mode */\r
 121                                         uint16_t HIDReportSize; /**< Size in bytes of the HID report descriptor in the device. */\r
 122 \r
 123                                         uint8_t LargestReportSize; /**< Largest report the device will send, in bytes. */\r
 124                                 } State; /**< State data for the USB class interface within the device. All elements in this section\r
 125                                                   *   <b>may</b> be set to initial values, but may also be ignored to default to sane values when\r
 126                                                   *   the interface is enumerated.\r
 127                                                   */\r
 128                         } USB_ClassInfo_HID_Host_t;\r
 129 \r
 130                 /* Enums: */\r
 131                         /** Enum for the possible error codes returned by the @ref HID_Host_ConfigurePipes() function. */\r
 132                         enum HID_Host_EnumerationFailure_ErrorCodes_t\r
 133                         {\r
 134                                 HID_ENUMERROR_NoError                    = 0, /**< Configuration Descriptor was processed successfully. */\r
 135                                 HID_ENUMERROR_InvalidConfigDescriptor    = 1, /**< The device returned an invalid Configuration Descriptor. */\r
 136                                 HID_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible HID interface was not found in the device's Configuration Descriptor. */\r
 137                                 HID_ENUMERROR_PipeConfigurationFailed    = 3, /**< One or more pipes for the specified interface could not be configured correctly. */\r
 138                         };\r
 139 \r
 140                 /* Function Prototypes: */\r
 141                         /** @brief Host interface configuration routine, to configure a given HID host interface instance using the Configuration\r
 142                          *  Descriptor read from an attached USB device. This function automatically updates the given HID Host instance's\r
 143                          *  state values and configures the pipes required to communicate with the interface if it is found within the\r
 144                          *  device. This should be called once after the stack has enumerated the attached device, while the host state\r
 145                          *  machine is in the Addressed state.\r
 146                          *\r
 147                          *  @note Once the device pipes are configured, the HID device's reporting protocol <b>must</b> be set via a call\r
 148                          *        to either the @ref HID_Host_SetBootProtocol() or @ref HID_Host_SetReportProtocol() function.\r
 149                          *\r
 150                          *  @param HIDInterfaceInfo       : Pointer to a structure containing a HID Class host configuration and state.\r
 151                          *  @param ConfigDescriptorSize   : Length of the attached device's Configuration Descriptor.\r
 152                          *  @param DeviceConfigDescriptor : Pointer to a buffer containing the attached device's Configuration Descriptor.\r
 153                          *\r
 154                          *  @return A value from the @ref HID_Host_EnumerationFailure_ErrorCodes_t enum.\r
 155                          */\r
 156                         uint8_t HID_Host_ConfigurePipes(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo,\r
 157                                                         uint16_t ConfigDescriptorSize,\r
 158                                                         void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);\r
 159 \r
 160 \r
 161                         /** @brief Receives a HID IN report from the attached HID device, when a report has been received on the HID IN Data pipe.\r
 162                          *\r
 163                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 164                          *       call will fail.\r
 165                          *\r
 166                          *  @note The destination buffer should be large enough to accommodate the largest report that the attached device\r
 167                          *        can generate.\r
 168                          *\r
 169                          *  @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.\r
 170                          *  @param Buffer           : Buffer to store the received report into.\r
 171                          *\r
 172                          *  @return An error code from the @ref Pipe_Stream_RW_ErrorCodes_t enum.\r
 173                          */\r
 174                         uint8_t HID_Host_ReceiveReport(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo,\r
 175                                                        void* Buffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);\r
 176 \r
 177                         #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)\r
 178                         /** @brief Receives a HID IN report from the attached device, by the report ID.\r
 179                          *\r
 180                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 181                          *       call will fail.\r
 182                          *\r
 183                          *  @note When the \c HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method is unavailable.\r
 184                          *\r
 185                          *  @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.\r
 186                          *  @param ReportID         : Report ID of the received report if ControlRequest is false, set by the to the Report ID to fetch.\r
 187                          *  @param Buffer            Buffer to store the received report into.\r
 188                          *\r
 189                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum.\r
 190                          */\r
 191                         uint8_t HID_Host_ReceiveReportByID(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo,\r
 192                                                            const uint8_t ReportID,\r
 193                                                            void* Buffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);\r
 194                         #endif\r
 195 \r
 196                         /** @brief Sends an OUT or FEATURE report to the currently attached HID device, using the device's OUT pipe if available,\r
 197                          *  or the device's Control pipe if not.\r
 198                          *\r
 199                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 200                          *       call will fail.\r
 201                          *\r
 202                          *  @note When the \c HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, the ReportID parameter is removed\r
 203                          *        from the parameter list of this function.\r
 204                          *\r
 205                          *  @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.\r
 206                          *  @param ReportID         : Report ID of the report to send to the device, or 0 if the device does not use report IDs.\r
 207                          *  @param ReportType       : Type of report to issue to the device, either @ref HID_REPORT_ITEM_Out or @ref HID_REPORT_ITEM_Feature.\r
 208                          *  @param Buffer           : Buffer containing the report to send to the attached device.\r
 209                          *  @param ReportSize       : Report size in bytes to send to the attached device.\r
 210                          *\r
 211                          *  @return An error code from the @ref USB_Host_SendControlErrorCodes_t enum if the DeviceUsesOUTPipe flag is set in\r
 212                          *          the interface's state structure, a value from the @ref Pipe_Stream_RW_ErrorCodes_t enum otherwise.\r
 213                          */\r
 214                         uint8_t HID_Host_SendReportByID(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo,\r
 215                         #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)\r
 216                                                         const uint8_t ReportID,\r
 217                         #endif\r
 218                                                         const uint8_t ReportType,\r
 219                                                         void* Buffer,\r
 220                                                         const uint16_t ReportSize) ATTR_NON_NULL_PTR_ARG(1)\r
 221                         #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)\r
 222                                                         ATTR_NON_NULL_PTR_ARG(4);\r
 223                         #else\r
 224                                                         ATTR_NON_NULL_PTR_ARG(3);\r
 225                         #endif\r
 226 \r
 227                         /** @brief Determines if a HID IN report has been received from the attached device on the data IN pipe.\r
 228                          *\r
 229                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 230                          *       call will fail.\r
 231                          *\r
 232                          *  @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.\r
 233                          *\r
 234                          *  @return Boolean \c true if a report has been received, \c false otherwise.\r
 235                          */\r
 236                         bool HID_Host_IsReportReceived(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 237 \r
 238                         /** @brief Switches the attached HID device's reporting protocol over to the Boot Report protocol mode, on supported devices.\r
 239                          *\r
 240                          *  @note When the \c HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method must still be called\r
 241                          *        to explicitly place the attached device into boot protocol mode before use.\r
 242                          *\r
 243                          *  @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.\r
 244                          *\r
 245                          *  @return @ref HID_ERROR_LOGICAL if the device does not support Boot Protocol mode, a value from the\r
 246                          *          @ref USB_Host_SendControlErrorCodes_t enum otherwise.\r
 247                          */\r
 248                         uint8_t HID_Host_SetBootProtocol(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 249 \r
 250                         /** @brief Sets the idle period for the attached HID device to the specified interval. The HID idle period determines the rate\r
 251                          *  at which the device should send a report, when no state changes have ocurred; i.e. on HID keyboards, this sets the\r
 252                          *  hardware key repeat interval.\r
 253                          *\r
 254                          *  @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.\r
 255                          *  @param MS               : Idle period as a multiple of four milliseconds, zero to disable hardware repeats\r
 256                          *\r
 257                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum.\r
 258                          */\r
 259                         uint8_t HID_Host_SetIdlePeriod(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo,\r
 260                                                        const uint16_t MS) ATTR_NON_NULL_PTR_ARG(1);\r
 261 \r
 262                         #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)\r
 263                         /** @brief Switches the attached HID device's reporting protocol over to the standard Report protocol mode. This also retrieves\r
 264                          *  and parses the device's HID report descriptor, so that the size of each report can be determined in advance.\r
 265                          *\r
 266                          *  @note Whether this function is used or not, the @ref CALLBACK_HIDParser_FilterHIDReportItem() callback from the HID\r
 267                          *        Report Parser this function references <b>must</b> be implemented in the user code.\r
 268                          *        \n\n\r
 269                          *\r
 270                          *  @note When the \c HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method is unavailable.\r
 271                          *\r
 272                          *  @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.\r
 273                          *\r
 274                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum if an error occurs while retrieving the HID\r
 275                          *          Report descriptor or the setting of the Report protocol, @ref HID_ERROR_LOGICAL if the HID interface does\r
 276                          *          not have a valid @ref HID_ReportInfo_t structure set in its configuration, a mask of @ref HID_ERROR_LOGICAL\r
 277                          *          and a value from the @ref HID_Parse_ErrorCodes_t otherwise.\r
 278                          */\r
 279                         uint8_t HID_Host_SetReportProtocol(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 280                         #endif\r
 281 \r
 282                 /* Inline Functions: */\r
 283                         /** @brief General management task for a given Human Interface Class host class interface, required for the correct operation of\r
 284                          *  the interface. This should be called frequently in the main program loop, before the master USB management task\r
 285                          *  @ref USB_USBTask().\r
 286                          *\r
 287                          *  @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.\r
 288                          *      @return Nothing\r
 289                          */\r
 290                         static inline void HID_Host_USBTask(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 291                         static inline void HID_Host_USBTask(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo)\r
 292                         {\r
 293                                 (void)HIDInterfaceInfo;\r
 294                         }\r
 295 \r
 296         /* Private Interface - For use in library only: */\r
 297         #if !defined(__DOXYGEN__)\r
 298                 /* Function Prototypes: */\r
 299                         #if defined(__INCLUDE_FROM_HID_HOST_C)\r
 300                                 static uint8_t DCOMP_HID_Host_NextHIDInterface(void* const CurrentDescriptor)\r
 301                                                                                ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);\r
 302                                 static uint8_t DCOMP_HID_Host_NextHIDDescriptor(void* const CurrentDescriptor)\r
 303                                                                                 ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);\r
 304                                 static uint8_t DCOMP_HID_Host_NextHIDInterfaceEndpoint(void* const CurrentDescriptor)\r
 305                                                                                        ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);\r
 306                         #endif\r
 307         #endif\r
 308 \r
 309         /* Disable C linkage for C++ Compilers: */\r
 310                 #if defined(__cplusplus)\r
 311                         }\r
 312                 #endif\r
 313 \r
 314 #endif\r
 315 \r
 316 /** @} */\r
 317 \r