git.sur5r.net Git - freertos/blob

   1 /*\r
   2  * @brief Common definitions and declarations for the library USB CDC 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_USBClassCDC\r
  34  *  @defgroup Group_USBClassCDCCommon  Common Class Definitions\r
  35  *\r
  36  *  @section Sec_ModDescription Module Description\r
  37  *  Constants, Types and Enum definitions that are common to both Device and Host modes for the USB\r
  38  *  CDC Class.\r
  39  *\r
  40  *  @{\r
  41  */\r
  42 \r
  43 #ifndef _CDC_CLASS_COMMON_H_\r
  44 #define _CDC_CLASS_COMMON_H_\r
  45 \r
  46         /* Includes: */\r
  47                 #include "../../Core/StdDescriptors.h"\r
  48 \r
  49         /* Enable C linkage for C++ Compilers: */\r
  50                 #if defined(__cplusplus)\r
  51                         extern "C" {\r
  52                 #endif\r
  53 \r
  54         /* Preprocessor Checks: */\r
  55                 #if !defined(__INCLUDE_FROM_CDC_DRIVER)\r
  56                         #error Do not include this file directly. Include LPCUSBlib/Drivers/USB.h instead.\r
  57                 #endif\r
  58 \r
  59         /* Macros: */\r
  60                 /** @name Virtual Control Line Masks */\r
  61                 //@{\r
  62                 /** Mask for the DTR handshake line for use with the @ref CDC_REQ_SetControlLineState class-specific request\r
  63                  *  from the host, to indicate that the DTR line state should be high.\r
  64                  */\r
  65                 #define CDC_CONTROL_LINE_OUT_DTR         (1 << 0)\r
  66 \r
  67                 /** Mask for the RTS handshake line for use with the @ref CDC_REQ_SetControlLineState class-specific request\r
  68                  *  from the host, to indicate that the RTS line state should be high.\r
  69                  */\r
  70                 #define CDC_CONTROL_LINE_OUT_RTS         (1 << 1)\r
  71 \r
  72                 /** Mask for the DCD handshake line for use with the @ref CDC_NOTIF_SerialState class-specific notification\r
  73                  *  from the device to the host, to indicate that the DCD line state is currently high.\r
  74                  */\r
  75                 #define CDC_CONTROL_LINE_IN_DCD          (1 << 0)\r
  76 \r
  77                 /** Mask for the DSR handshake line for use with the @ref CDC_NOTIF_SerialState class-specific notification\r
  78                  *  from the device to the host, to indicate that the DSR line state is currently high.\r
  79                  */\r
  80                 #define CDC_CONTROL_LINE_IN_DSR          (1 << 1)\r
  81 \r
  82                 /** Mask for the BREAK handshake line for use with the @ref CDC_NOTIF_SerialState class-specific notification\r
  83                  *  from the device to the host, to indicate that the BREAK line state is currently high.\r
  84                  */\r
  85                 #define CDC_CONTROL_LINE_IN_BREAK        (1 << 2)\r
  86 \r
  87                 /** Mask for the RING handshake line for use with the @ref CDC_NOTIF_SerialState class-specific notification\r
  88                  *  from the device to the host, to indicate that the RING line state is currently high.\r
  89                  */\r
  90                 #define CDC_CONTROL_LINE_IN_RING         (1 << 3)\r
  91 \r
  92                 /** Mask for use with the @ref CDC_NOTIF_SerialState class-specific notification from the device to the host,\r
  93                  *  to indicate that a framing error has occurred on the virtual serial port.\r
  94                  */\r
  95                 #define CDC_CONTROL_LINE_IN_FRAMEERROR   (1 << 4)\r
  96 \r
  97                 /** Mask for use with the @ref CDC_NOTIF_SerialState class-specific notification from the device to the host,\r
  98                  *  to indicate that a parity error has occurred on the virtual serial port.\r
  99                  */\r
 100                 #define CDC_CONTROL_LINE_IN_PARITYERROR  (1 << 5)\r
 101 \r
 102                 /** Mask for use with the @ref CDC_NOTIF_SerialState class-specific notification from the device to the host,\r
 103                  *  to indicate that a data overrun error has occurred on the virtual serial port.\r
 104                  */\r
 105                 #define CDC_CONTROL_LINE_IN_OVERRUNERROR (1 << 6)\r
 106                 //@}\r
 107                 \r
 108                 /** Macro to define a CDC class-specific functional descriptor. CDC functional descriptors have a\r
 109                  *  uniform structure but variable sized data payloads, thus cannot be represented accurately by\r
 110                  *  a single typedef struct. A macro is used instead so that functional descriptors can be created\r
 111                  *  easily by specifying the size of the payload. This allows \c sizeof() to work correctly.\r
 112                  *\r
 113                  *  @param DataSize  Size in bytes of the CDC functional descriptor's data payload.\r
 114                  */\r
 115                 #define CDC_FUNCTIONAL_DESCRIPTOR(DataSize)        \\r
 116                      struct                                        \\r
 117                      {                                             \\r
 118                           USB_Descriptor_Header_t Header;          \\r
 119                               uint8_t                 SubType;         \\r
 120                           uint8_t                 Data[DataSize];  \\r
 121                      }\r
 122 \r
 123         /* Enums: */\r
 124                 /** Enum for possible Class, Subclass and Protocol values of device and interface descriptors relating to the CDC\r
 125                  *  device class.\r
 126                  */\r
 127                 enum CDC_Descriptor_ClassSubclassProtocol_t\r
 128                 {\r
 129                         CDC_CSCP_CDCClass               = 0x02, /**< Descriptor Class value indicating that the device or interface\r
 130                                                                  *   belongs to the CDC class.\r
 131                                                                  */\r
 132                         CDC_CSCP_NoSpecificSubclass     = 0x00, /**< Descriptor Subclass value indicating that the device or interface\r
 133                                                                  *   belongs to no specific subclass of the CDC class.\r
 134                                                                  */\r
 135                         CDC_CSCP_ACMSubclass            = 0x02, /**< Descriptor Subclass value indicating that the device or interface\r
 136                                                                  *   belongs to the Abstract Control Model CDC subclass.\r
 137                                                                  */\r
 138                         CDC_CSCP_ATCommandProtocol      = 0x01, /**< Descriptor Protocol value indicating that the device or interface\r
 139                                                                  *   belongs to the AT Command protocol of the CDC class.\r
 140                                                                  */\r
 141                         CDC_CSCP_NoSpecificProtocol     = 0x00, /**< Descriptor Protocol value indicating that the device or interface\r
 142                                                                  *   belongs to no specific protocol of the CDC class.\r
 143                                                                  */\r
 144                         CDC_CSCP_VendorSpecificProtocol = 0xFF, /**< Descriptor Protocol value indicating that the device or interface\r
 145                                                                  *   belongs to a vendor-specific protocol of the CDC class.\r
 146                                                                  */\r
 147                         CDC_CSCP_CDCDataClass           = 0x0A, /**< Descriptor Class value indicating that the device or interface\r
 148                                                                  *   belongs to the CDC Data class.\r
 149                                                                  */\r
 150                         CDC_CSCP_NoDataSubclass         = 0x00, /**< Descriptor Subclass value indicating that the device or interface\r
 151                                                                  *   belongs to no specific subclass of the CDC data class.\r
 152                                                                  */\r
 153                         CDC_CSCP_NoDataProtocol         = 0x00, /**< Descriptor Protocol value indicating that the device or interface\r
 154                                                                  *   belongs to no specific protocol of the CDC data class.\r
 155                                                                  */\r
 156                 };\r
 157                 \r
 158                 /** Enum for the CDC class specific control requests that can be issued by the USB bus host. */\r
 159                 enum CDC_ClassRequests_t\r
 160                 {\r
 161                         CDC_REQ_SendEncapsulatedCommand = 0x00, /**< CDC class-specific request to send an encapsulated command to the device. */\r
 162                         CDC_REQ_GetEncapsulatedResponse = 0x01, /**< CDC class-specific request to retrieve an encapsulated command response from the device. */\r
 163                         CDC_REQ_SetLineEncoding         = 0x20, /**< CDC class-specific request to set the current virtual serial port configuration settings. */\r
 164                         CDC_REQ_GetLineEncoding         = 0x21, /**< CDC class-specific request to get the current virtual serial port configuration settings. */\r
 165                         CDC_REQ_SetControlLineState     = 0x22, /**< CDC class-specific request to set the current virtual serial port handshake line states. */\r
 166                         CDC_REQ_SendBreak               = 0x23, /**< CDC class-specific request to send a break to the receiver via the carrier channel. */\r
 167                 };\r
 168 \r
 169                 /** Enum for the CDC class specific notification requests that can be issued by a CDC device to a host. */\r
 170                 enum CDC_ClassNotifications_t\r
 171                 {\r
 172                         CDC_NOTIF_SerialState               = 0x20, /**< Notification type constant for a change in the virtual serial port\r
 173                                                                      *   handshake line states, for use with a @ref USB_Request_Header_t\r
 174                                                                      *   notification structure when sent to the host via the CDC notification\r
 175                                                                      *   endpoint.\r
 176                                                                      */\r
 177                 };\r
 178 \r
 179                 /** Enum for the CDC class specific interface descriptor subtypes. */\r
 180                 enum CDC_DescriptorSubtypes_t\r
 181                 {\r
 182                         CDC_DSUBTYPE_CSInterface_Header           = 0x00, /**< CDC class-specific Header functional descriptor. */\r
 183                         CDC_DSUBTYPE_CSInterface_CallManagement   = 0x01, /**< CDC class-specific Call Management functional descriptor. */\r
 184                         CDC_DSUBTYPE_CSInterface_ACM              = 0x02, /**< CDC class-specific Abstract Control Model functional descriptor. */\r
 185                         CDC_DSUBTYPE_CSInterface_DirectLine       = 0x03, /**< CDC class-specific Direct Line functional descriptor. */\r
 186                         CDC_DSUBTYPE_CSInterface_TelephoneRinger  = 0x04, /**< CDC class-specific Telephone Ringer functional descriptor. */\r
 187                         CDC_DSUBTYPE_CSInterface_TelephoneCall    = 0x05, /**< CDC class-specific Telephone Call functional descriptor. */\r
 188                         CDC_DSUBTYPE_CSInterface_Union            = 0x06, /**< CDC class-specific Union functional descriptor. */\r
 189                         CDC_DSUBTYPE_CSInterface_CountrySelection = 0x07, /**< CDC class-specific Country Selection functional descriptor. */\r
 190                         CDC_DSUBTYPE_CSInterface_TelephoneOpModes = 0x08, /**< CDC class-specific Telephone Operation Modes functional descriptor. */\r
 191                         CDC_DSUBTYPE_CSInterface_USBTerminal      = 0x09, /**< CDC class-specific USB Terminal functional descriptor. */\r
 192                         CDC_DSUBTYPE_CSInterface_NetworkChannel   = 0x0A, /**< CDC class-specific Network Channel functional descriptor. */\r
 193                         CDC_DSUBTYPE_CSInterface_ProtocolUnit     = 0x0B, /**< CDC class-specific Protocol Unit functional descriptor. */\r
 194                         CDC_DSUBTYPE_CSInterface_ExtensionUnit    = 0x0C, /**< CDC class-specific Extension Unit functional descriptor. */\r
 195                         CDC_DSUBTYPE_CSInterface_MultiChannel     = 0x0D, /**< CDC class-specific Multi-Channel Management functional descriptor. */\r
 196                         CDC_DSUBTYPE_CSInterface_CAPI             = 0x0E, /**< CDC class-specific Common ISDN API functional descriptor. */\r
 197                         CDC_DSUBTYPE_CSInterface_Ethernet         = 0x0F, /**< CDC class-specific Ethernet functional descriptor. */\r
 198                         CDC_DSUBTYPE_CSInterface_ATM              = 0x10, /**< CDC class-specific Asynchronous Transfer Mode functional descriptor. */\r
 199                 };\r
 200 \r
 201                 /** Enum for the possible line encoding formats of a virtual serial port. */\r
 202                 enum CDC_LineEncodingFormats_t\r
 203                 {\r
 204                         CDC_LINEENCODING_OneStopBit          = 0, /**< Each frame contains one stop bit. */\r
 205                         CDC_LINEENCODING_OneAndAHalfStopBits = 1, /**< Each frame contains one and a half stop bits. */\r
 206                         CDC_LINEENCODING_TwoStopBits         = 2, /**< Each frame contains two stop bits. */\r
 207                 };\r
 208 \r
 209                 /** Enum for the possible line encoding parity settings of a virtual serial port. */\r
 210                 enum CDC_LineEncodingParity_t\r
 211                 {\r
 212                         CDC_PARITY_None  = 0, /**< No parity bit mode on each frame. */\r
 213                         CDC_PARITY_Odd   = 1, /**< Odd parity bit mode on each frame. */\r
 214                         CDC_PARITY_Even  = 2, /**< Even parity bit mode on each frame. */\r
 215                         CDC_PARITY_Mark  = 3, /**< Mark parity bit mode on each frame. */\r
 216                         CDC_PARITY_Space = 4, /**< Space parity bit mode on each frame. */\r
 217                 };\r
 218 \r
 219         /* Type Defines: */\r
 220                 /** @brief CDC class-specific Functional Header Descriptor (nxpUSBlib naming conventions).\r
 221                  *\r
 222                  *  Type define for a CDC class-specific functional header descriptor. This indicates to the host that the device\r
 223                  *  contains one or more CDC functional data descriptors, which give the CDC interface's capabilities and configuration.\r
 224                  *  See the CDC class specification for more details.\r
 225                  *\r
 226                  *  @see @ref USB_CDC_StdDescriptor_FunctionalHeader_t for the version of this type with standard element names.\r
 227                  *\r
 228                  *  @note Regardless of CPU architecture, these values should be stored as little endian.\r
 229                  */\r
 230                 typedef ATTR_IAR_PACKED struct\r
 231                 {\r
 232                         USB_Descriptor_Header_t Header; /**< Regular descriptor header containing the descriptor's type and length. */\r
 233                         uint8_t                 Subtype; /**< Sub type value used to distinguish between CDC class-specific descriptors,\r
 234                                                           *   must be @ref CDC_DSUBTYPE_CSInterface_Header.\r
 235                                                           */\r
 236                         uint16_t                CDCSpecification; /**< Version number of the CDC specification implemented by the device,\r
 237                                                                    *   encoded in BCD format.\r
 238                                                                    */\r
 239                 } ATTR_PACKED USB_CDC_Descriptor_FunctionalHeader_t;\r
 240 \r
 241                 /** @brief CDC class-specific Functional Header Descriptor (USB-IF naming conventions).\r
 242                  *\r
 243                  *  Type define for a CDC class-specific functional header descriptor. This indicates to the host that the device\r
 244                  *  contains one or more CDC functional data descriptors, which give the CDC interface's capabilities and configuration.\r
 245                  *  See the CDC class specification for more details.\r
 246                  *\r
 247                  *  @see @ref USB_CDC_Descriptor_FunctionalHeader_t for the version of this type with non-standard nxpUSBlib specific\r
 248                  *       element names.\r
 249                  *\r
 250                  *  @note Regardless of CPU architecture, these values should be stored as little endian.\r
 251                  */\r
 252                 typedef ATTR_IAR_PACKED struct\r
 253                 {\r
 254                         uint8_t  bFunctionLength; /**< Size of the descriptor, in bytes. */\r
 255                         uint8_t  bDescriptorType; /**< Type of the descriptor, either a value in @ref USB_DescriptorTypes_t or a value\r
 256                                                    *   given by the specific class.\r
 257                                                    */\r
 258                         uint8_t  bDescriptorSubType; /**< Sub type value used to distinguish between CDC class-specific descriptors,\r
 259                                                       *   must be @ref CDC_DSUBTYPE_CSInterface_Header.\r
 260                                                       */\r
 261                         uint16_t bcdCDC; /**< Version number of the CDC specification implemented by the device, encoded in BCD format. */\r
 262                 } ATTR_PACKED USB_CDC_StdDescriptor_FunctionalHeader_t;\r
 263 \r
 264                 /** @brief CDC class-specific Functional ACM Descriptor (nxpUSBlib naming conventions).\r
 265                  *\r
 266                  *  Type define for a CDC class-specific functional ACM descriptor. This indicates to the host that the CDC interface\r
 267                  *  supports the CDC ACM subclass of the CDC specification. See the CDC class specification for more details.\r
 268                  *\r
 269                  *  @see @ref USB_CDC_StdDescriptor_FunctionalACM_t for the version of this type with standard element names.\r
 270                  *\r
 271                  *  @note Regardless of CPU architecture, these values should be stored as little endian.\r
 272                  */\r
 273                 typedef ATTR_IAR_PACKED struct\r
 274                 {\r
 275                         USB_Descriptor_Header_t Header; /**< Regular descriptor header containing the descriptor's type and length. */\r
 276                         uint8_t                 Subtype; /**< Sub type value used to distinguish between CDC class-specific descriptors,\r
 277                                                           *   must be @ref CDC_DSUBTYPE_CSInterface_ACM.\r
 278                                                           */\r
 279                         uint8_t                 Capabilities; /**< Capabilities of the ACM interface, given as a bit mask. For most devices,\r
 280                                                                *   this should be set to a fixed value of 0x06 - for other capabilities, refer\r
 281                                                                *   to the CDC ACM specification.\r
 282                                                                */\r
 283                 } ATTR_PACKED USB_CDC_Descriptor_FunctionalACM_t;\r
 284 \r
 285                 /** @brief CDC class-specific Functional ACM Descriptor (USB-IF naming conventions).\r
 286                  *\r
 287                  *  Type define for a CDC class-specific functional ACM descriptor. This indicates to the host that the CDC interface\r
 288                  *  supports the CDC ACM subclass of the CDC specification. See the CDC class specification for more details.\r
 289                  *\r
 290                  *  @see @ref USB_CDC_Descriptor_FunctionalACM_t for the version of this type with non-standard nxpUSBlib specific\r
 291                  *       element names.\r
 292                  *\r
 293                  *  @note Regardless of CPU architecture, these values should be stored as little endian.\r
 294                  */\r
 295                 typedef ATTR_IAR_PACKED struct\r
 296                 {\r
 297                         uint8_t bFunctionLength; /**< Size of the descriptor, in bytes. */\r
 298                         uint8_t bDescriptorType; /**< Type of the descriptor, either a value in @ref USB_DescriptorTypes_t or a value\r
 299                                                   *   given by the specific class.\r
 300                                                   */\r
 301                         uint8_t bDescriptorSubType; /**< Sub type value used to distinguish between CDC class-specific descriptors,\r
 302                                                      *   must be @ref CDC_DSUBTYPE_CSInterface_ACM.\r
 303                                                      */\r
 304                         uint8_t bmCapabilities; /**< Capabilities of the ACM interface, given as a bit mask. For most devices,\r
 305                                                  *   this should be set to a fixed value of 0x06 - for other capabilities, refer\r
 306                                                  *   to the CDC ACM specification.\r
 307                                                  */\r
 308                 } ATTR_PACKED USB_CDC_StdDescriptor_FunctionalACM_t;\r
 309 \r
 310                 /** @brief CDC class-specific Functional Union Descriptor (nxpUSBlib naming conventions).\r
 311                  *\r
 312                  *  Type define for a CDC class-specific functional Union descriptor. This indicates to the host that specific\r
 313                  *  CDC control and data interfaces are related. See the CDC class specification for more details.\r
 314                  *\r
 315                  *  @see @ref USB_CDC_StdDescriptor_FunctionalUnion_t for the version of this type with standard element names.\r
 316                  *\r
 317                  *  @note Regardless of CPU architecture, these values should be stored as little endian.\r
 318                  */\r
 319                 typedef ATTR_IAR_PACKED struct\r
 320                 {\r
 321                         USB_Descriptor_Header_t Header; /**< Regular descriptor header containing the descriptor's type and length. */\r
 322                         uint8_t                 Subtype; /**< Sub type value used to distinguish between CDC class-specific descriptors,\r
 323                                                           *   must be @ref CDC_DSUBTYPE_CSInterface_Union.\r
 324                                                           */\r
 325                         uint8_t                 MasterInterfaceNumber; /**< Interface number of the CDC Control interface. */\r
 326                         uint8_t                 SlaveInterfaceNumber; /**< Interface number of the CDC Data interface. */\r
 327                 } ATTR_PACKED USB_CDC_Descriptor_FunctionalUnion_t;\r
 328 \r
 329                 /** @brief CDC class-specific Functional Union Descriptor (USB-IF naming conventions).\r
 330                  *\r
 331                  *  Type define for a CDC class-specific functional Union descriptor. This indicates to the host that specific\r
 332                  *  CDC control and data interfaces are related. See the CDC class specification for more details.\r
 333                  *\r
 334                  *  @see @ref USB_CDC_Descriptor_FunctionalUnion_t for the version of this type with non-standard nxpUSBlib specific\r
 335                  *       element names.\r
 336                  *\r
 337                  *  @note Regardless of CPU architecture, these values should be stored as little endian.\r
 338                  */\r
 339                 typedef ATTR_IAR_PACKED struct\r
 340                 {\r
 341                         uint8_t bFunctionLength; /**< Size of the descriptor, in bytes. */\r
 342                         uint8_t bDescriptorType; /**< Type of the descriptor, either a value in @ref USB_DescriptorTypes_t or a value\r
 343                                                   *   given by the specific class.\r
 344                                                   */\r
 345                         uint8_t bDescriptorSubType; /**< Sub type value used to distinguish between CDC class-specific descriptors,\r
 346                                                      *   must be @ref CDC_DSUBTYPE_CSInterface_Union.\r
 347                                                      */\r
 348                         uint8_t bMasterInterface; /**< Interface number of the CDC Control interface. */\r
 349                         uint8_t bSlaveInterface0; /**< Interface number of the CDC Data interface. */\r
 350                 } ATTR_PACKED USB_CDC_StdDescriptor_FunctionalUnion_t;\r
 351                 \r
 352                 /** @brief CDC Virtual Serial Port Line Encoding Settings Structure.\r
 353                  *\r
 354                  *  Type define for a CDC Line Encoding structure, used to hold the various encoding parameters for a virtual\r
 355                  *  serial port.\r
 356                  *\r
 357                  *  @note Regardless of CPU architecture, these values should be stored as little endian.\r
 358                  */\r
 359                 typedef ATTR_IAR_PACKED struct\r
 360                 {\r
 361                         uint32_t BaudRateBPS; /**< Baud rate of the virtual serial port, in bits per second. */\r
 362                         uint8_t  CharFormat; /**< Character format of the virtual serial port, a value from the\r
 363                                                                   *   @ref CDC_LineEncodingFormats_t enum.\r
 364                                                                   */\r
 365                         uint8_t  ParityType; /**< Parity setting of the virtual serial port, a value from the\r
 366                                                                   *   @ref CDC_LineEncodingParity_t enum.\r
 367                                                                   */\r
 368                         uint8_t  DataBits; /**< Bits of data per character of the virtual serial port. */\r
 369                 } ATTR_PACKED CDC_LineEncoding_t;\r
 370 \r
 371         /* Disable C linkage for C++ Compilers: */\r
 372                 #if defined(__cplusplus)\r
 373                         }\r
 374                 #endif\r
 375 \r
 376 #endif\r
 377 \r
 378 /** @} */\r
 379 \r