git.sur5r.net Git - freertos/blob

   1 /*\r
   2  * @brief Host mode driver for the library USB RNDIS 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_USBClassRNDIS\r
  34  *  @defgroup Group_USBClassRNDISHost RNDIS 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/RNDIS.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 Microsoft RNDIS Ethernet\r
  42  *  USB Class driver.\r
  43  *\r
  44  *  @{\r
  45  */\r
  46 \r
  47 #ifndef __RNDIS_CLASS_HOST_H__\r
  48 #define __RNDIS_CLASS_HOST_H__\r
  49 \r
  50         /* Includes: */\r
  51                 #include "../../USB.h"\r
  52                 #include "../Common/RNDISClassCommon.h"\r
  53 \r
  54         /* Enable C linkage for C++ Compilers: */\r
  55                 #if defined(__cplusplus)\r
  56                         extern "C" {\r
  57                 #endif\r
  58 \r
  59         /* Preprocessor Checks: */\r
  60                 #if !defined(__INCLUDE_FROM_RNDIS_DRIVER)\r
  61                         #error Do not include this file directly. Include LPCUSBlib/Drivers/USB.h instead.\r
  62                 #endif\r
  63 \r
  64         /* Public Interface - May be used in end-application: */\r
  65                 /* Type Defines: */\r
  66                         /** @brief RNDIS Class Host Mode Configuration and State Structure.\r
  67                          *\r
  68                          *  Class state structure. An instance of this structure should be made within the user application,\r
  69                          *  and passed to each of the RNDIS class driver functions as the \c RNDISInterfaceInfo parameter. This\r
  70                          *  stores each RNDIS interface's configuration and state information.\r
  71                          */\r
  72                         typedef struct\r
  73                         {\r
  74                                 const struct\r
  75                                 {\r
  76                                         uint8_t  DataINPipeNumber; /**< Pipe number of the RNDIS interface's IN data pipe. */\r
  77                                         bool     DataINPipeDoubleBank; /**< Indicates if the RNDIS interface's IN data pipe should use double banking. */\r
  78 \r
  79                                         uint8_t  DataOUTPipeNumber; /**< Pipe number of the RNDIS interface's OUT data pipe. */\r
  80                                         bool     DataOUTPipeDoubleBank; /**< Indicates if the RNDIS interface's OUT data pipe should use double banking. */\r
  81 \r
  82                                         uint8_t  NotificationPipeNumber; /**< Pipe number of the RNDIS interface's IN notification endpoint, if used. */\r
  83                                         bool     NotificationPipeDoubleBank; /**< Indicates if the RNDIS interface's notification pipe should use double banking. */\r
  84 \r
  85                                         uint32_t HostMaxPacketSize; /**< Maximum size of a packet which can be buffered by the host. */\r
  86                                         uint8_t  PortNumber;            /**< Port number that this interface is running.\r
  87                                                                                                 */\r
  88                                 } Config; /**< Config data for the USB class interface within the device. All elements in this section\r
  89                                            *   <b>must</b> be set or the interface will fail to enumerate and operate correctly.\r
  90                                            */\r
  91                                 struct\r
  92                                 {\r
  93                                         bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid\r
  94                                                         *   after @ref RNDIS_Host_ConfigurePipes() is called and the Host state machine is in the\r
  95                                                         *   Configured state.\r
  96                                                         */\r
  97                                         uint8_t ControlInterfaceNumber; /**< Interface index of the RNDIS control interface within the attached device. */\r
  98 \r
  99                                         uint16_t DataINPipeSize; /**< Size in bytes of the RNDIS interface's IN data pipe. */\r
 100                                         uint16_t DataOUTPipeSize;  /**< Size in bytes of the RNDIS interface's OUT data pipe. */\r
 101                                         uint16_t NotificationPipeSize;  /**< Size in bytes of the RNDIS interface's IN notification pipe, if used. */\r
 102 \r
 103                                         uint32_t DeviceMaxPacketSize; /**< Maximum size of a packet which can be buffered by the attached RNDIS device. */\r
 104 \r
 105                                         uint32_t RequestID; /**< Request ID counter to give a unique ID for each command/response pair. */\r
 106                                 } State; /**< State data for the USB class interface within the device. All elements in this section\r
 107                                                   *   <b>may</b> be set to initial values, but may also be ignored to default to sane values when\r
 108                                                   *   the interface is enumerated.\r
 109                                                   */\r
 110                         } USB_ClassInfo_RNDIS_Host_t;\r
 111 \r
 112                 /* Enums: */\r
 113                         /** Enum for the possible error codes returned by the @ref RNDIS_Host_ConfigurePipes() function. */\r
 114                         enum RNDIS_Host_EnumerationFailure_ErrorCodes_t\r
 115                         {\r
 116                                 RNDIS_ENUMERROR_NoError                    = 0, /**< Configuration Descriptor was processed successfully. */\r
 117                                 RNDIS_ENUMERROR_InvalidConfigDescriptor    = 1, /**< The device returned an invalid Configuration Descriptor. */\r
 118                                 RNDIS_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible RNDIS interface was not found in the device's Configuration Descriptor. */\r
 119                                 RNDIS_ENUMERROR_PipeConfigurationFailed    = 3, /**< One or more pipes for the specified interface could not be configured correctly. */\r
 120                         };\r
 121 \r
 122                 /* Function Prototypes: */\r
 123                         /** @brief Host interface configuration routine, to configure a given RNDIS host interface instance using the Configuration\r
 124                          *  Descriptor read from an attached USB device. This function automatically updates the given RNDIS Host instance's\r
 125                          *  state values and configures the pipes required to communicate with the interface if it is found within the device.\r
 126                          *  This should be called once after the stack has enumerated the attached device, while the host state machine is in\r
 127                          *  the Addressed state.\r
 128                          *\r
 129                          *  @param RNDISInterfaceInfo     : Pointer to a structure containing an RNDIS Class host configuration and state.\r
 130                          *  @param ConfigDescriptorSize   : Length of the attached device's Configuration Descriptor.\r
 131                          *  @param DeviceConfigDescriptor : Pointer to a buffer containing the attached device's Configuration Descriptor.\r
 132                          *\r
 133                          *  @return A value from the @ref RNDIS_Host_EnumerationFailure_ErrorCodes_t enum.\r
 134                          */\r
 135                         uint8_t RNDIS_Host_ConfigurePipes(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo,\r
 136                                                           uint16_t ConfigDescriptorSize,\r
 137                                                           void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);\r
 138 \r
 139                         /** @brief Sends a RNDIS KEEPALIVE command to the device, to ensure that it does not enter standby mode after periods\r
 140                          *  of long inactivity.\r
 141                          *\r
 142                          *  @param RNDISInterfaceInfo : Pointer to a structure containing an RNDIS Class host configuration and state.\r
 143                          *\r
 144                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum or @ref RNDIS_ERROR_LOGICAL_CMD_FAILED if the device returned a\r
 145                          *          logical command failure.\r
 146                          */\r
 147                         uint8_t RNDIS_Host_SendKeepAlive(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 148 \r
 149                         /** @brief Initializes the attached RNDIS device's RNDIS interface. This should be called after the device's pipes have been\r
 150                          *  configured via the call to @ref RNDIS_Host_ConfigurePipes().\r
 151                          *\r
 152                          *  @param RNDISInterfaceInfo : Pointer to a structure containing an RNDIS Class host configuration and state.\r
 153                          *\r
 154                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum or @ref RNDIS_ERROR_LOGICAL_CMD_FAILED if the\r
 155                          *          device returned a logical command failure.\r
 156                          */\r
 157                         uint8_t RNDIS_Host_InitializeDevice(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 158 \r
 159                         /** @brief Sets a given RNDIS property of an attached RNDIS device.\r
 160                          *\r
 161                          *  @param RNDISInterfaceInfo : Pointer to a structure containing an RNDIS Class host configuration and state.\r
 162                          *  @param Oid                : OID number of the parameter to set.\r
 163                          *  @param Buffer             : Pointer to where the property data is to be sourced from.\r
 164                          *  @param Length             : Length in bytes of the property data to sent to the device.\r
 165                          *\r
 166                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum or @ref RNDIS_ERROR_LOGICAL_CMD_FAILED if the\r
 167                          *          device returned a logical command failure.\r
 168                          */\r
 169                         uint8_t RNDIS_Host_SetRNDISProperty(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo,\r
 170                                                             const uint32_t Oid,\r
 171                                                             void* Buffer,\r
 172                                                             const uint16_t Length) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);\r
 173 \r
 174                         /** @brief Gets a given RNDIS property of an attached RNDIS device.\r
 175                          *\r
 176                          *  @param RNDISInterfaceInfo : Pointer to a structure containing an RNDIS Class host configuration and state.\r
 177                          *  @param Oid                : OID number of the parameter to get.\r
 178                          *  @param Buffer             : Pointer to where the property data is to be written to.\r
 179                          *  @param MaxLength          : Length in bytes of the destination buffer size.\r
 180                          *\r
 181                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum or @ref RNDIS_ERROR_LOGICAL_CMD_FAILED if the\r
 182                          *          device returned a logical command failure.\r
 183                          */\r
 184                         uint8_t RNDIS_Host_QueryRNDISProperty(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo,\r
 185                                                               const uint32_t Oid,\r
 186                                                               void* Buffer,\r
 187                                                               const uint16_t MaxLength) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);\r
 188 \r
 189                         /** @brief Determines if a packet is currently waiting for the host to read in and process.\r
 190                          *\r
 191                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 192                          *       call will fail.\r
 193                          *\r
 194                          *  @param RNDISInterfaceInfo : Pointer to a structure containing an RNDIS Class host configuration and state.\r
 195                          *\r
 196                          *  @return Boolean \c true if a packet is waiting to be read in by the host, \c false otherwise.\r
 197                          */\r
 198                         bool RNDIS_Host_IsPacketReceived(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 199 \r
 200                         /** @brief Retrieves the next pending packet from the device, discarding the remainder of the RNDIS packet header to leave\r
 201                          *  only the packet contents for processing by the host in the nominated buffer.\r
 202                          *\r
 203                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 204                          *       call will fail.\r
 205                          *\r
 206                          *  @param RNDISInterfaceInfo : Pointer to a structure containing an RNDIS Class host configuration and state.\r
 207                          *  @param Buffer             : Pointer to a buffer where the packer data is to be written to.\r
 208                          *  @param PacketLength       : Pointer to where the length in bytes of the read packet is to be stored.\r
 209                          *\r
 210                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum.\r
 211                          */\r
 212                         uint8_t RNDIS_Host_ReadPacket(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo,\r
 213                                                       void* Buffer,\r
 214                                                       uint16_t* const PacketLength) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2)\r
 215                                                       ATTR_NON_NULL_PTR_ARG(3);\r
 216 \r
 217                         /** @brief Sends the given packet to the attached RNDIS device, after adding a RNDIS packet message header.\r
 218                          *\r
 219                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 220                          *       call will fail.\r
 221                          *\r
 222                          *  @param RNDISInterfaceInfo : Pointer to a structure containing an RNDIS Class host configuration and state.\r
 223                          *  @param Buffer             : Pointer to a buffer where the packer data is to be read from.\r
 224                          *  @param PacketLength       : Length in bytes of the packet to send.\r
 225                          *\r
 226                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum.\r
 227                          */\r
 228                         uint8_t RNDIS_Host_SendPacket(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo,\r
 229                                                       void* Buffer,\r
 230                                                       const uint16_t PacketLength) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);\r
 231 \r
 232                 /* Inline Functions: */\r
 233                         /** @brief General management task for a given RNDIS host class interface, required for the correct operation of the interface. This should\r
 234                          *  be called frequently in the main program loop, before the master USB management task @ref USB_USBTask().\r
 235                          *\r
 236                          *  @param RNDISInterfaceInfo : Pointer to a structure containing an RNDIS Class host configuration and state.\r
 237                          *      @return Nothing\r
 238                          */\r
 239                         static inline void RNDIS_Host_USBTask(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;\r
 240                         static inline void RNDIS_Host_USBTask(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo)\r
 241                         {\r
 242                                 (void)RNDISInterfaceInfo;\r
 243                         }\r
 244 \r
 245         /* Private Interface - For use in library only: */\r
 246         #if !defined(__DOXYGEN__)\r
 247                 /* Function Prototypes: */\r
 248                         #if defined(__INCLUDE_FROM_RNDIS_HOST_C)\r
 249                                 static uint8_t RNDIS_SendEncapsulatedCommand(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo,\r
 250                                                                              void* Buffer,\r
 251                                                                              const uint16_t Length) ATTR_NON_NULL_PTR_ARG(1)\r
 252                                                                              ATTR_NON_NULL_PTR_ARG(2);\r
 253                                 static uint8_t RNDIS_GetEncapsulatedResponse(USB_ClassInfo_RNDIS_Host_t* const RNDISInterfaceInfo,\r
 254                                                                              void* Buffer,\r
 255                                                                              const uint16_t Length) ATTR_NON_NULL_PTR_ARG(1)\r
 256                                                                              ATTR_NON_NULL_PTR_ARG(2);\r
 257 \r
 258                                 static uint8_t DCOMP_RNDIS_Host_NextRNDISControlInterface(void* const CurrentDescriptor)\r
 259                                                                                           ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);\r
 260                                 static uint8_t DCOMP_RNDIS_Host_NextRNDISDataInterface(void* const CurrentDescriptor)\r
 261                                                                                        ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);\r
 262                                 static uint8_t DCOMP_RNDIS_Host_NextRNDISInterfaceEndpoint(void* const CurrentDescriptor)\r
 263                                                                                            ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);\r
 264                         #endif\r
 265         #endif\r
 266 \r
 267         /* Disable C linkage for C++ Compilers: */\r
 268                 #if defined(__cplusplus)\r
 269                         }\r
 270                 #endif\r
 271 \r
 272 #endif\r
 273 \r
 274 /** @} */\r
 275 \r