git.sur5r.net Git - freertos/blob

   1 /*\r
   2  * @brief Host Controller Driver functions\r
   3  *\r
   4  * @note\r
   5  * Copyright(C) NXP Semiconductors, 2012\r
   6  * All rights reserved.\r
   7  *\r
   8  * @par\r
   9  * Software that is described herein is for illustrative purposes only\r
  10  * which provides customers with programming information regarding the\r
  11  * LPC products.  This software is supplied "AS IS" without any warranties of\r
  12  * any kind, and NXP Semiconductors and its licensor disclaim any and\r
  13  * all warranties, express or implied, including all implied warranties of\r
  14  * merchantability, fitness for a particular purpose and non-infringement of\r
  15  * intellectual property rights.  NXP Semiconductors assumes no responsibility\r
  16  * or liability for the use of the software, conveys no license or rights under any\r
  17  * patent, copyright, mask work right, or any other intellectual property rights in\r
  18  * or to any products. NXP Semiconductors reserves the right to make changes\r
  19  * in the software without notification. NXP Semiconductors also makes no\r
  20  * representation or warranty that such application will be suitable for the\r
  21  * specified use without further testing or modification.\r
  22  *\r
  23  * @par\r
  24  * Permission to use, copy, modify, and distribute this software and its\r
  25  * documentation is hereby granted, under NXP Semiconductors' and its\r
  26  * licensor's relevant copyrights in the software, without fee, provided that it\r
  27  * is used in conjunction with NXP Semiconductors microcontrollers.  This\r
  28  * copyright, permission, and disclaimer notice must appear in all copies of\r
  29  * this code.\r
  30  */\r
  31 \r
  32 /** @ingroup Group_Host\r
  33  *  @defgroup Group_HCD Host Controller Drivers\r
  34  *  @{\r
  35  */\r
  36 #ifndef __LPC_HCD_H__\r
  37 #define __LPC_HCD_H__\r
  38 \r
  39 #include "../../../../Common/Common.h"\r
  40 #include "../StdRequestType.h"  // FIXME should be USBTask.h instead\r
  41 #include "../HAL/HAL.h"\r
  42 #include <string.h>\r
  43 #include <stdio.h>\r
  44 \r
  45 /** Used with \ref HcdDataTransfer() to set maximum endpoint size for transfer length\r
  46  */\r
  47 #define HCD_ENDPOINT_MAXPACKET_XFER_LEN                 0xFFEEFFEE\r
  48 \r
  49 /** Similar to boolean type\r
  50  */\r
  51 #define YES                                 1\r
  52 \r
  53 /** Similar to boolean type\r
  54  */\r
  55 #define NO                                  0\r
  56 \r
  57 /** Maximum number of endpoints/pipes that a single USB host core can support\r
  58  */\r
  59 #define HCD_MAX_ENDPOINT                    8\r
  60 \r
  61 /** Pre-defined counter value for reseting USB host core\r
  62  */\r
  63 #define HC_RESET_TIMEOUT                    10\r
  64 \r
  65 /** Pre-defined counter value for transferring\r
  66  */\r
  67 #define TRANSFER_TIMEOUT_MS                 1000\r
  68 \r
  69 /** Pre-defined counter value for reseting USB port\r
  70  */\r
  71 #define PORT_RESET_PERIOD_MS                100\r
  72 \r
  73 /* Control / Bulk transfer is always enabled     */\r
  74 /** Flag to enable processing for interrupt transfer\r
  75  *  Select \ref YES to enable or \ref NO if disable\r
  76  */\r
  77 #define INTERRUPT_LIST_ENABLE               YES\r
  78 \r
  79 /** Flag to enable processing for isochronous transfer\r
  80  *  Select \ref YES to enable or \ref NO if disable\r
  81  */\r
  82 #define ISO_LIST_ENABLE                     YES\r
  83 \r
  84 /** Declare labels for all USB transfer types\r
  85  */\r
  86 typedef enum {\r
  87         CONTROL_TRANSFER,\r
  88         ISOCHRONOUS_TRANSFER,\r
  89         BULK_TRANSFER,\r
  90         INTERRUPT_TRANSFER\r
  91 } HCD_TRANSFER_TYPE;\r
  92 \r
  93 /** Declare labels for all USB transfer direction\r
  94  */\r
  95 typedef enum {\r
  96         SETUP_TRANSFER,\r
  97         IN_TRANSFER,\r
  98         OUT_TRANSFER\r
  99 } HCD_TRANSFER_DIR;\r
 100 \r
 101 /** Declare labels for supported USB transfer speeds\r
 102  */\r
 103 typedef enum {\r
 104         FULL_SPEED = 0,\r
 105         LOW_SPEED,\r
 106         HIGH_SPEED\r
 107 } HCD_USB_SPEED;\r
 108 \r
 109 /** Declare status/completion code for host processing\r
 110  */\r
 111 typedef enum {\r
 112         HCD_STATUS_OK = 0,                                              /**< Transfer/process completion normal*/\r
 113 \r
 114         HCD_STATUS_TRANSFER_CRC,                                /**< Transfer/process completion fail: CRC error */\r
 115         HCD_STATUS_TRANSFER_BitStuffing,                /**< Transfer/process completion fail: bit stuffing error */\r
 116         HCD_STATUS_TRANSFER_DataToggleMismatch, /**< Transfer/process completion fail: data toggle error */\r
 117         HCD_STATUS_TRANSFER_Stall,                              /**< Transfer/process completion fail: endpoint stall */\r
 118         HCD_STATUS_TRANSFER_DeviceNotResponding,/**< Transfer/process completion fail: connected device hung or ... */\r
 119 \r
 120         HCD_STATUS_TRANSFER_PIDCheckFailure,    /**< Transfer/process completion fail: PID error */\r
 121         HCD_STATUS_TRANSFER_UnexpectedPID,              /**< Transfer/process completion fail: PID error */\r
 122         HCD_STATUS_TRANSFER_DataOverrun,                /**< Transfer/process completion fail: data over run */\r
 123         HCD_STATUS_TRANSFER_DataUnderrun,               /**< Transfer/process completion fail: data under run */\r
 124         HCD_STATUS_TRANSFER_CC_Reserved1,               /**< Transfer/process completion fail: Reserved */\r
 125 \r
 126         HCD_STATUS_TRANSFER_CC_Reserved2,               /**< Transfer/process completion fail: Reserved */\r
 127         HCD_STATUS_TRANSFER_BufferOverrun,              /**< Transfer/process completion fail: buffer over run */\r
 128         HCD_STATUS_TRANSFER_BufferUnderrun,             /**< Transfer/process completion fail: buffer under run */\r
 129         HCD_STATUS_TRANSFER_NotAccessed,                /**< Transfer/process completion fail: Reserved */\r
 130         HCD_STATUS_TRANSFER_Reserved,                   /**< Transfer/process completion fail: Reserved */\r
 131 \r
 132         HCD_STATUS_STRUCTURE_IS_FREE,                   /**< USB transfer status: USB data structure is free to use */\r
 133         HCD_STATUS_TO_BE_REMOVED,                               /**< USB transfer status: USB data structure need to be freed */\r
 134         HCD_STATUS_TRANSFER_QUEUED,                             /**< USB transfer status: transfer descriptor has been set up and queued */\r
 135         HCD_STATUS_TRANSFER_COMPLETED,                  /**< USB transfer status: transfer descriptor finished */\r
 136         HCD_STATUS_TRANSFER_ERROR,                              /**< USB transfer status: transfer descriptor finished with error */\r
 137 \r
 138         HCD_STATUS_NOT_ENOUGH_MEMORY,                   /**< USB transfer set up status: not enough memory */\r
 139         HCD_STATUS_NOT_ENOUGH_ENDPOINT,                 /**< USB transfer set up status: not enough endpoint */\r
 140         HCD_STATUS_NOT_ENOUGH_GTD,                              /**< USB transfer set up status: not enough general transfer descriptor (OHCI)*/\r
 141         HCD_STATUS_NOT_ENOUGH_ITD,                              /**< USB transfer set up status: not enough isochronous transfer descriptor */\r
 142         HCD_STATUS_NOT_ENOUGH_QTD,                              /**< USB transfer set up status: not enough queue transfer descrptor (EHCI) */\r
 143 \r
 144         HCD_STATUS_NOT_ENOUGH_HS_ITD,                   /**< USB transfer set up status: not enough high speed isochronous trsfer descriptor */\r
 145         HCD_STATUS_NOT_ENOUGH_SITD,                             /**< USB transfer set up status: not enough split isochronous transfer descriptor */\r
 146         HCD_STATUS_DATA_OVERFLOW,                               /**< USB transfer set up status: data over flow */\r
 147         HCD_STATUS_DEVICE_DISCONNECTED,                 /**< USB transfer set up status: device disconnected */\r
 148         HCD_STATUS_TRANSFER_TYPE_NOT_SUPPORTED, /**< USB transfer set up status: transfer is not supported */\r
 149 \r
 150         HCD_STATUS_PIPEHANDLE_INVALID,                  /**< USB transfer set up status: pipe handle information is not valid */\r
 151         HCD_STATUS_PARAMETER_INVALID                    /**< USB transfer set up status: wrong supply parameters */\r
 152 } HCD_STATUS;\r
 153 \r
 154 /**\r
 155  * @brief  Initiate host driver\r
 156  *\r
 157  * @param  HostID               : USB port number\r
 158  * @return \ref HCD_STATUS code\r
 159  */\r
 160 HCD_STATUS HcdInitDriver (uint8_t HostID);\r
 161 \r
 162 /**\r
 163  * @brief  De-initiate host driver\r
 164  *\r
 165  * @param  HostID               : USB port number\r
 166  * @return \ref HCD_STATUS code\r
 167  */\r
 168 HCD_STATUS HcdDeInitDriver(uint8_t HostID);\r
 169 \r
 170 /**\r
 171  * @brief  Interrupt service routine for host mode\r
 172  *                 This function must be called in chip's USB interrupt routine\r
 173  *\r
 174  * @param  HostID               : USB port number\r
 175  * @return nothing\r
 176  */\r
 177 void HcdIrqHandler(uint8_t HostID);\r
 178 \r
 179 /**\r
 180  * @brief  Perform USB bus reset\r
 181  *\r
 182  * @param  HostID               : USB port number\r
 183  * @return \ref HCD_STATUS code\r
 184  */\r
 185 HCD_STATUS HcdRhPortReset(uint8_t HostID);\r
 186 \r
 187 /**\r
 188  * @brief  Turn on 5V USB VBUS\r
 189  *\r
 190  * @param  HostID               : USB port number\r
 191  * @return \ref HCD_STATUS code\r
 192  */\r
 193 HCD_STATUS HcdRhPortEnable(uint8_t HostID);\r
 194 \r
 195 /**\r
 196  * @brief  Turn off 5V USB VBUS\r
 197  *\r
 198  * @param  HostID               : USB port number\r
 199  * @return \ref HCD_STATUS code\r
 200  */\r
 201 HCD_STATUS HcdRhPortDisable(uint8_t HostID);\r
 202 \r
 203 /**\r
 204  * @brief  Get operation speed of connected device\r
 205  *\r
 206  * @param  HostID               : USB port number\r
 207  * @param  DeviceSpeed  : return device speed through pointer of type \ref HCD_USB_SPEED\r
 208  * @return \ref HCD_STATUS code\r
 209  */\r
 210 HCD_STATUS HcdGetDeviceSpeed(uint8_t HostID, HCD_USB_SPEED *DeviceSpeed);\r
 211 \r
 212 /**\r
 213  * @brief  Get current frame number\r
 214  *\r
 215  * @param  HostID               : USB port number\r
 216  * @return frame number\r
 217  */\r
 218 uint32_t HcdGetFrameNumber(uint8_t HostID);\r
 219 \r
 220 /**\r
 221  * @brief  Setup a pipe to connect to device's logical endpoint\r
 222  *\r
 223  * @param  HostID               : USB port number\r
 224  * @param  DeviceAddr   : address of connected device\r
 225  * @param  DeviceSpeed  : speed of connected device in format \ref HCD_USB_SPEED\r
 226  * @param  EndpointNo   : connected logical endpoint number\r
 227  * @param  TransferType : transfer type of this link in format \ref HCD_TRANSFER_TYPE\r
 228  * @param  TransferDir  : direction of this link in format \ref HCD_TRANSFER_DIR\r
 229  * @param  MaxPacketSize: maximum size of connected endpoint\r
 230  * @param  Interval             : polling frequency for this transfer type, only apply for period transfer\r
 231  * @param  Mult                 : used for isochronous transfer to determine number of packets sent in one transaction\r
 232  * @param  HSHubDevAddr : currently not use this parameter\r
 233  * @param  HSHubPortNum : currently not use this parameter\r
 234  * @param  PipeHandle   : pointer to return pipe handle information\r
 235  * @return \ref HCD_STATUS code\r
 236  */\r
 237 HCD_STATUS HcdOpenPipe(uint8_t HostID,\r
 238                                            uint8_t DeviceAddr,\r
 239                                            HCD_USB_SPEED DeviceSpeed,\r
 240                                            uint8_t EndpointNo,\r
 241                                            HCD_TRANSFER_TYPE TransferType,\r
 242                                            HCD_TRANSFER_DIR TransferDir,\r
 243                                            uint16_t MaxPacketSize,\r
 244                                            uint8_t Interval,\r
 245                                            uint8_t Mult,\r
 246                                            uint8_t HSHubDevAddr,\r
 247                                            uint8_t HSHubPortNum,\r
 248                                            uint32_t *const PipeHandle);\r
 249 \r
 250 /**\r
 251  * @brief  Delete the link between USB host and device's logical endpoint\r
 252  *\r
 253  * @param  PipeHandle   : encoded pipe handle information\r
 254  * @return \ref HCD_STATUS code\r
 255  */\r
 256 HCD_STATUS HcdClosePipe(uint32_t PipeHandle);\r
 257 \r
 258 /**\r
 259  * @brief  Cancel a processing transfer\r
 260  *\r
 261  * @param  PipeHandle   : encoded pipe handle information\r
 262  * @return \ref HCD_STATUS code\r
 263  */\r
 264 HCD_STATUS HcdCancelTransfer(uint32_t PipeHandle);\r
 265 \r
 266 /**\r
 267  * @brief  Clear stall status for connected endpoint\r
 268  *\r
 269  * @param  PipeHandle   : encoded pipe handle information\r
 270  * @return \ref HCD_STATUS code\r
 271  */\r
 272 HCD_STATUS HcdClearEndpointHalt(uint32_t PipeHandle);\r
 273 \r
 274 /**\r
 275  * @brief  Perform a control transfer\r
 276  *\r
 277  * @param  PipeHandle   : encoded pipe handle information\r
 278  * @param  pDeviceRequest: pointer to \ref USB_Request_Header_t structure\r
 279  * @param  buffer               : pointer to share buffer used in data phase\r
 280  * @return \ref HCD_STATUS code\r
 281  */\r
 282 HCD_STATUS HcdControlTransfer(uint32_t PipeHandle,\r
 283                                                           const USB_Request_Header_t *const pDeviceRequest,\r
 284                                                           uint8_t *const buffer);\r
 285 \r
 286 /**\r
 287  * @brief  Perform a non-control transfer\r
 288  *\r
 289  * @param  PipeHandle   : encoded pipe handle information\r
 290  * @param  buffer               : pointer to transferred data buffer\r
 291  * @param  length               : size of this transfer\r
 292  * @param  pActualTransferred: return actual transfer bytes through pointer\r
 293  * @return \ref HCD_STATUS code\r
 294  */\r
 295 HCD_STATUS HcdDataTransfer(uint32_t PipeHandle,\r
 296                                                    uint8_t *const buffer,\r
 297                                                    uint32_t const length,\r
 298                                                    uint16_t *const pActualTransferred);\r
 299 \r
 300 /**\r
 301  * @brief  Get current pipe status\r
 302  *\r
 303  * @param  PipeHandle   : encoded pipe handle information\r
 304  * @return \ref HCD_STATUS code\r
 305  */\r
 306 HCD_STATUS HcdGetPipeStatus(uint32_t PipeHandle);\r
 307 \r
 308 /**\r
 309  * @brief  Set size of each packet in a continuous data transfer\r
 310  *\r
 311  * @param  PipeHandle   : encoded pipe handle information\r
 312  * @param  packetsize   : packet size\r
 313  * @return \ref HCD_STATUS code\r
 314  */\r
 315 void HcdSetStreamPacketSize(uint32_t PipeHandle, uint16_t packetsize);\r
 316 \r
 317 #ifdef LPCUSBlib_DEBUG\r
 318         #define hcd_printf          printf\r
 319 void assert_status_ok_message(HCD_STATUS status,\r
 320                                                           char const *mess,\r
 321                                                           char const *func,\r
 322                                                           char const *file,\r
 323                                                           uint32_t const line);\r
 324 \r
 325 #else\r
 326         #define hcd_printf(...)\r
 327         #define assert_status_ok_message(...)\r
 328 #endif\r
 329 \r
 330 #define ASSERT_STATUS_OK_MESSAGE(sts, message) \\r
 331         do { \\r
 332                 HCD_STATUS status = (sts); \\r
 333                 assert_status_ok_message(status, message, __func__, __FILE__, __LINE__); \\r
 334                 if (HCD_STATUS_OK != status) { \\r
 335                         return status; \\r
 336                 } \\r
 337         } while (0)\r
 338 \r
 339 #define ASSERT_STATUS_OK(sts)       ASSERT_STATUS_OK_MESSAGE(sts, NULL)\r
 340 \r
 341 #if defined(__LPC_OHCI_C__) || defined(__LPC_EHCI_C__)\r
 342 \r
 343 void  HcdDelayUS (uint32_t  delay);\r
 344 \r
 345 void  HcdDelayMS (uint32_t  delay);\r
 346 \r
 347 /**\r
 348  * @brief  Verify if input parameters are supported\r
 349  *\r
 350  * @param  HostID               : USB port number\r
 351  * @param  DeviceAddr   : address of connected device\r
 352  * @param  DeviceSpeed  : speed of connected device in format \ref HCD_USB_SPEED\r
 353  * @param  EndpointNumber: connected logical endpoint number\r
 354  * @param  TransferType : transfer type of this link in format \ref HCD_TRANSFER_TYPE\r
 355  * @param  TransferDir  : direction of this link in format \ref HCD_TRANSFER_DIR\r
 356  * @param  MaxPacketSize: maximum size of connected endpoint\r
 357  * @param  Interval             : polling frequency for this transfer type, only apply for period transfer\r
 358  * @param  Mult                 : used for isochronous transfer to determine number of packets sent in one transaction\r
 359  * @return \ref HCD_STATUS code\r
 360  */\r
 361 HCD_STATUS OpenPipe_VerifyParameters(uint8_t HostID,\r
 362                                                                          uint8_t DeviceAddr,\r
 363                                                                          HCD_USB_SPEED DeviceSpeed,\r
 364                                                                          uint8_t EndpointNumber,\r
 365                                                                          HCD_TRANSFER_TYPE TransferType,\r
 366                                                                          HCD_TRANSFER_DIR TransferDir,\r
 367                                                                          uint16_t MaxPacketSize,\r
 368                                                                          uint8_t Interval,\r
 369                                                                          uint8_t Mult);\r
 370 \r
 371 /**\r
 372  * @brief  Modify an address to a desired alignment\r
 373  *\r
 374  * @param  Value                : input address\r
 375  * @return output aligned address\r
 376  */\r
 377 static INLINE uint32_t Align32(uint32_t Value)\r
 378 {\r
 379         return Value & 0xFFFFFFE0UL;    /* Bit 31 .. 5 */\r
 380 }\r
 381 \r
 382 /**\r
 383  * @brief  Modify an address to a desired alignment\r
 384  *\r
 385  * @param  alignment    : alignment desired value\r
 386  * @param  Value                : input address\r
 387  * @return output aligned address\r
 388  */\r
 389 static INLINE uint32_t Aligned(uint32_t alignment, uint32_t Value)\r
 390 {\r
 391         return Value & (~(alignment - 1));\r
 392 }\r
 393 \r
 394 /**\r
 395  * @brief  Modify an address to desired alignment\r
 396  *\r
 397  * @param  Value                : input address\r
 398  * @return output aligned address\r
 399  */\r
 400 static INLINE uint32_t Align4k(uint32_t Value)\r
 401 {\r
 402         return Value & 0xFFFFF000;      /* Bit 31 .. 5 */\r
 403 }\r
 404 \r
 405 /**\r
 406  * @brief  Modify an address to desired offset\r
 407  *\r
 408  * @param  Value                : input address\r
 409  * @return output offset address\r
 410  */\r
 411 static INLINE uint32_t Offset4k(uint32_t Value)\r
 412 {\r
 413         return Value & 0xFFF;\r
 414 }\r
 415 \r
 416 #endif\r
 417 \r
 418 #endif\r
 419 \r
 420 /** @} */\r