1 /*********************************************************************** 2 * $Id:: mw_usbd_hw.h 331 2012-08-09 18:54:34Z usb10131 $ 3 * 4 * Project: USB device ROM Stack 5 * 6 * Description: 7 * USB Hardware Function prototypes. 8 * 9 *********************************************************************** 10 * Copyright(C) 2011, NXP Semiconductor 11 * All rights reserved. 12 * 13 * Software that is described herein is for illustrative purposes only 14 * which provides customers with programming information regarding the 15 * products. This software is supplied "AS IS" without any warranties. 16 * NXP Semiconductors assumes no responsibility or liability for the 17 * use of the software, conveys no license or title under any patent, 18 * copyright, or mask work right to the product. NXP Semiconductors 19 * reserves the right to make changes in the software without 20 * notification. NXP Semiconductors also make no representation or 21 * warranty that such application will be suitable for the specified 22 * use without further testing or modification. 23 **********************************************************************/ 24 #ifndef __USBHW_H__ 25 #define __USBHW_H__ 26 27 #include "error.h" 28 #include "usbd.h" 29 #include "usbd_core.h" 30 31 /** \file 32 * \brief USB Hardware Function prototypes. 33 * 34 * Definition of functions exported by ROM based Device Controller Driver (DCD). 35 * 36 */ 37 38 /** \ingroup Group_USBD 39 * @defgroup USBD_HW USB Device Controller Driver 40 * \section Sec_HWModDescription Module Description 41 * The Device Controller Driver Layer implements the routines to deal directly with the hardware. 42 */ 43 44 /** \ingroup USBD_HW 45 * USB Endpoint/class handler Callback Events. 46 * 47 */ 48 enum USBD_EVENT_T { 49 USB_EVT_SETUP =1, /**< 1 Setup Packet received */ 50 USB_EVT_OUT, /**< 2 OUT Packet received */ 51 USB_EVT_IN, /**< 3 IN Packet sent */ 52 USB_EVT_OUT_NAK, /**< 4 OUT Packet - Not Acknowledged */ 53 USB_EVT_IN_NAK, /**< 5 IN Packet - Not Acknowledged */ 54 USB_EVT_OUT_STALL, /**< 6 OUT Packet - Stalled */ 55 USB_EVT_IN_STALL, /**< 7 IN Packet - Stalled */ 56 USB_EVT_OUT_DMA_EOT, /**< 8 DMA OUT EP - End of Transfer */ 57 USB_EVT_IN_DMA_EOT, /**< 9 DMA IN EP - End of Transfer */ 58 USB_EVT_OUT_DMA_NDR, /**< 10 DMA OUT EP - New Descriptor Request */ 59 USB_EVT_IN_DMA_NDR, /**< 11 DMA IN EP - New Descriptor Request */ 60 USB_EVT_OUT_DMA_ERR, /**< 12 DMA OUT EP - Error */ 61 USB_EVT_IN_DMA_ERR, /**< 13 DMA IN EP - Error */ 62 USB_EVT_RESET, /**< 14 Reset event recieved */ 63 USB_EVT_SOF, /**< 15 Start of Frame event */ 64 USB_EVT_DEV_STATE, /**< 16 Device status events */ 65 USB_EVT_DEV_ERROR /**< 17 Device error events */ 66 }; 67 68 /** 69 * \brief Hardware API functions structure. 70 * \ingroup USBD_HW 71 * 72 * This module exposes functions which interact directly with USB device controller hardware. 73 * 74 */ 75 typedef struct USBD_HW_API 76 { 77 /** \fn uint32_t GetMemSize(USBD_API_INIT_PARAM_T* param) 78 * Function to determine the memory required by the USB device stack's DCD and core layers. 79 * 80 * This function is called by application layer before calling pUsbApi->hw->Init(), to allocate memory used 81 * by DCD and core layers. The application should allocate the memory which is accessible by USB 82 * controller/DMA controller. 83 * \note Some memory areas are not accessible by all bus masters. 84 * 85 * \param[in] param Structure containing USB device stack initialization parameters. 86 * \return Returns the required memory size in bytes. 87 */ 88 uint32_t (*GetMemSize)(USBD_API_INIT_PARAM_T* param); 89 90 /** \fn ErrorCode_t Init(USBD_HANDLE_T* phUsb, USB_CORE_DESCS_T* pDesc, USBD_API_INIT_PARAM_T* param) 91 * Function to initialize USB device stack's DCD and core layers. 92 * 93 * This function is called by application layer to initialize USB hardware and core layers. 94 * On successful initialization the function returns a handle to USB device stack which should 95 * be passed to the rest of the functions. 96 * 97 * \param[in,out] phUsb Pointer to the USB device stack handle of type USBD_HANDLE_T. 98 * \param[in] pDesc Structure containing pointers to various descriptor arrays needed by the stack. 99 * These descriptors are reported to USB host as part of enumerations process. 100 * \param[in] param Structure containing USB device stack initialization parameters. 101 * \return Returns \ref ErrorCode_t type to indicate success or error condition. 102 * \retval LPC_OK(0) On success 103 * \retval ERR_USBD_BAD_MEM_BUF(0x0004000b) When insufficient memory buffer is passed or memory 104 * is not aligned on 2048 boundary. 105 */ 106 ErrorCode_t (*Init)(USBD_HANDLE_T* phUsb, USB_CORE_DESCS_T* pDesc, USBD_API_INIT_PARAM_T* param); 107 108 /** \fn void Connect(USBD_HANDLE_T hUsb, uint32_t con) 109 * Function to make USB device visible/invisible on the USB bus. 110 * 111 * This function is called after the USB initialization. This function uses the soft connect 112 * feature to make the device visible on the USB bus. This function is called only after the 113 * application is ready to handle the USB data. The enumeration process is started by the 114 * host after the device detection. The driver handles the enumeration process according to 115 * the USB descriptors passed in the USB initialization function. 116 * 117 * \param[in] hUsb Handle to the USB device stack. 118 * \param[in] con States whether to connect (1) or to disconnect (0). 119 * \return Nothing. 120 */ 121 void (*Connect)(USBD_HANDLE_T hUsb, uint32_t con); 122 123 /** \fn void ISR(USBD_HANDLE_T hUsb) 124 * Function to USB device controller interrupt events. 125 * 126 * When the user application is active the interrupt handlers are mapped in the user flash 127 * space. The user application must provide an interrupt handler for the USB interrupt and 128 * call this function in the interrupt handler routine. The driver interrupt handler takes 129 * appropriate action according to the data received on the USB bus. 130 * 131 * \param[in] hUsb Handle to the USB device stack. 132 * \return Nothing. 133 */ 134 void (*ISR)(USBD_HANDLE_T hUsb); 135 136 /** \fn void Reset(USBD_HANDLE_T hUsb) 137 * Function to Reset USB device stack and hardware controller. 138 * 139 * Reset USB device stack and hardware controller. Disables all endpoints except EP0. 140 * Clears all pending interrupts and resets endpoint transfer queues. 141 * This function is called internally by pUsbApi->hw->init() and from reset event. 142 * 143 * \param[in] hUsb Handle to the USB device stack. 144 * \return Nothing. 145 */ 146 void (*Reset)(USBD_HANDLE_T hUsb); 147 148 /** \fn void ForceFullSpeed(USBD_HANDLE_T hUsb, uint32_t cfg) 149 * Function to force high speed USB device to operate in full speed mode. 150 * 151 * This function is useful for testing the behavior of current device when connected 152 * to a full speed only hosts. 153 * 154 * \param[in] hUsb Handle to the USB device stack. 155 * \param[in] cfg When 1 - set force full-speed or 156 * 0 - clear force full-speed. 157 * \return Nothing. 158 */ 159 void (*ForceFullSpeed )(USBD_HANDLE_T hUsb, uint32_t cfg); 160 161 /** \fn void WakeUpCfg(USBD_HANDLE_T hUsb, uint32_t cfg) 162 * Function to configure USB device controller to wake-up host on remote events. 163 * 164 * This function is called by application layer to configure the USB device controller 165 * to wakeup on remote events. It is recommended to call this function from users's 166 * USB_WakeUpCfg() callback routine registered with stack. 167 * \note User's USB_WakeUpCfg() is registered with stack by setting the USB_WakeUpCfg member 168 * of USBD_API_INIT_PARAM_T structure before calling pUsbApi->hw->Init() routine. 169 * Certain USB device controllers needed to keep some clocks always on to generate 170 * resume signaling through pUsbApi->hw->WakeUp(). This hook is provided to support 171 * such controllers. In most controllers cases this is an empty routine. 172 * 173 * \param[in] hUsb Handle to the USB device stack. 174 * \param[in] cfg When 1 - Configure controller to wake on remote events or 175 * 0 - Configure controller not to wake on remote events. 176 * \return Nothing. 177 */ 178 void (*WakeUpCfg)(USBD_HANDLE_T hUsb, uint32_t cfg); 179 180 /** \fn void SetAddress(USBD_HANDLE_T hUsb, uint32_t adr) 181 * Function to set USB address assigned by host in device controller hardware. 182 * 183 * This function is called automatically when USB_REQUEST_SET_ADDRESS request is received 184 * by the stack from USB host. 185 * This interface is provided to users to invoke this function in other scenarios which are not 186 * handle by current stack. In most user applications this function is not called directly. 187 * Also this function can be used by users who are selectively modifying the USB device stack's 188 * standard handlers through callback interface exposed by the stack. 189 * 190 * \param[in] hUsb Handle to the USB device stack. 191 * \param[in] adr USB bus Address to which the device controller should respond. Usually 192 * assigned by the USB host. 193 * \return Nothing. 194 */ 195 void (*SetAddress)(USBD_HANDLE_T hUsb, uint32_t adr); 196 197 /** \fn void Configure(USBD_HANDLE_T hUsb, uint32_t cfg) 198 * Function to configure device controller hardware with selected configuration. 199 * 200 * This function is called automatically when USB_REQUEST_SET_CONFIGURATION request is received 201 * by the stack from USB host. 202 * This interface is provided to users to invoke this function in other scenarios which are not 203 * handle by current stack. In most user applications this function is not called directly. 204 * Also this function can be used by users who are selectively modifying the USB device stack's 205 * standard handlers through callback interface exposed by the stack. 206 * 207 * \param[in] hUsb Handle to the USB device stack. 208 * \param[in] cfg Configuration index. 209 * \return Nothing. 210 */ 211 void (*Configure)(USBD_HANDLE_T hUsb, uint32_t cfg); 212 213 /** \fn void ConfigEP(USBD_HANDLE_T hUsb, USB_ENDPOINT_DESCRIPTOR *pEPD) 214 * Function to configure USB Endpoint according to descriptor. 215 * 216 * This function is called automatically when USB_REQUEST_SET_CONFIGURATION request is received 217 * by the stack from USB host. All the endpoints associated with the selected configuration 218 * are configured. 219 * This interface is provided to users to invoke this function in other scenarios which are not 220 * handle by current stack. In most user applications this function is not called directly. 221 * Also this function can be used by users who are selectively modifying the USB device stack's 222 * standard handlers through callback interface exposed by the stack. 223 * 224 * \param[in] hUsb Handle to the USB device stack. 225 * \param[in] pEPD Endpoint descriptor structure defined in USB 2.0 specification. 226 * \return Nothing. 227 */ 228 void (*ConfigEP)(USBD_HANDLE_T hUsb, USB_ENDPOINT_DESCRIPTOR *pEPD); 229 230 /** \fn void DirCtrlEP(USBD_HANDLE_T hUsb, uint32_t dir) 231 * Function to set direction for USB control endpoint EP0. 232 * 233 * This function is called automatically by the stack on need basis. 234 * This interface is provided to users to invoke this function in other scenarios which are not 235 * handle by current stack. In most user applications this function is not called directly. 236 * Also this function can be used by users who are selectively modifying the USB device stack's 237 * standard handlers through callback interface exposed by the stack. 238 * 239 * \param[in] hUsb Handle to the USB device stack. 240 * \param[in] cfg When 1 - Set EP0 in IN transfer mode 241 * 0 - Set EP0 in OUT transfer mode 242 * \return Nothing. 243 */ 244 void (*DirCtrlEP)(USBD_HANDLE_T hUsb, uint32_t dir); 245 246 /** \fn void EnableEP(USBD_HANDLE_T hUsb, uint32_t EPNum) 247 * Function to enable selected USB endpoint. 248 * 249 * This function enables interrupts on selected endpoint. 250 * 251 * \param[in] hUsb Handle to the USB device stack. 252 * \param[in] EPNum Endpoint number as per USB specification. 253 * ie. An EP1_IN is represented by 0x81 number. 254 * \return Nothing. 255 */ 256 void (*EnableEP)(USBD_HANDLE_T hUsb, uint32_t EPNum); 257 258 /** \fn void DisableEP(USBD_HANDLE_T hUsb, uint32_t EPNum) 259 * Function to disable selected USB endpoint. 260 * 261 * This function disables interrupts on selected endpoint. 262 * 263 * \param[in] hUsb Handle to the USB device stack. 264 * \param[in] EPNum Endpoint number as per USB specification. 265 * ie. An EP1_IN is represented by 0x81 number. 266 * \return Nothing. 267 */ 268 void (*DisableEP)(USBD_HANDLE_T hUsb, uint32_t EPNum); 269 270 /** \fn void ResetEP(USBD_HANDLE_T hUsb, uint32_t EPNum) 271 * Function to reset selected USB endpoint. 272 * 273 * This function flushes the endpoint buffers and resets data toggle logic. 274 * 275 * \param[in] hUsb Handle to the USB device stack. 276 * \param[in] EPNum Endpoint number as per USB specification. 277 * ie. An EP1_IN is represented by 0x81 number. 278 * \return Nothing. 279 */ 280 void (*ResetEP)(USBD_HANDLE_T hUsb, uint32_t EPNum); 281 282 /** \fn void SetStallEP(USBD_HANDLE_T hUsb, uint32_t EPNum) 283 * Function to STALL selected USB endpoint. 284 * 285 * Generates STALL signaling for requested endpoint. 286 * 287 * \param[in] hUsb Handle to the USB device stack. 288 * \param[in] EPNum Endpoint number as per USB specification. 289 * ie. An EP1_IN is represented by 0x81 number. 290 * \return Nothing. 291 */ 292 void (*SetStallEP)(USBD_HANDLE_T hUsb, uint32_t EPNum); 293 294 /** \fn void ClrStallEP(USBD_HANDLE_T hUsb, uint32_t EPNum) 295 * Function to clear STALL state for the requested endpoint. 296 * 297 * This function clears STALL state for the requested endpoint. 298 * 299 * \param[in] hUsb Handle to the USB device stack. 300 * \param[in] EPNum Endpoint number as per USB specification. 301 * ie. An EP1_IN is represented by 0x81 number. 302 * \return Nothing. 303 */ 304 void (*ClrStallEP)(USBD_HANDLE_T hUsb, uint32_t EPNum); 305 306 /** \fn ErrorCode_t SetTestMode(USBD_HANDLE_T hUsb, uint8_t mode) 307 * Function to set high speed USB device controller in requested test mode. 308 * 309 * USB-IF requires the high speed device to be put in various test modes 310 * for electrical testing. This USB device stack calls this function whenever 311 * it receives USB_REQUEST_CLEAR_FEATURE request for USB_FEATURE_TEST_MODE. 312 * Users can put the device in test mode by directly calling this function. 313 * Returns ERR_USBD_INVALID_REQ when device controller is full-speed only. 314 * 315 * \param[in] hUsb Handle to the USB device stack. 316 * \param[in] mode Test mode defined in USB 2.0 electrical testing specification. 317 * \return Returns \ref ErrorCode_t type to indicate success or error condition. 318 * \retval LPC_OK(0) - On success 319 * \retval ERR_USBD_INVALID_REQ(0x00040001) - Invalid test mode or 320 * Device controller is full-speed only. 321 */ 322 ErrorCode_t (*SetTestMode)(USBD_HANDLE_T hUsb, uint8_t mode); 323 324 /** \fn uint32_t ReadEP(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData) 325 * Function to read data received on the requested endpoint. 326 * 327 * This function is called by USB stack and the application layer to read the data 328 * received on the requested endpoint. 329 * 330 * \param[in] hUsb Handle to the USB device stack. 331 * \param[in] EPNum Endpoint number as per USB specification. 332 * ie. An EP1_IN is represented by 0x81 number. 333 * \param[in,out] pData Pointer to the data buffer where data is to be copied. 334 * \return Returns the number of bytes copied to the buffer. 335 */ 336 uint32_t (*ReadEP)(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData); 337 338 /** \fn uint32_t ReadReqEP(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData, uint32_t len) 339 * Function to queue read request on the specified endpoint. 340 * 341 * This function is called by USB stack and the application layer to queue a read request 342 * on the specified endpoint. 343 * 344 * \param[in] hUsb Handle to the USB device stack. 345 * \param[in] EPNum Endpoint number as per USB specification. 346 * ie. An EP1_IN is represented by 0x81 number. 347 * \param[in,out] pData Pointer to the data buffer where data is to be copied. This buffer 348 * address should be accessible by USB DMA master. 349 * \param[in] len Length of the buffer passed. 350 * \return Returns the length of the requested buffer. 351 */ 352 uint32_t (*ReadReqEP)(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData, uint32_t len); 353 354 /** \fn uint32_t ReadSetupPkt(USBD_HANDLE_T hUsb, uint32_t EPNum, uint32_t *pData) 355 * Function to read setup packet data received on the requested endpoint. 356 * 357 * This function is called by USB stack and the application layer to read setup packet data 358 * received on the requested endpoint. 359 * 360 * \param[in] hUsb Handle to the USB device stack. 361 * \param[in] EPNum Endpoint number as per USB specification. 362 * ie. An EP0_IN is represented by 0x80 number. 363 * \param[in,out] pData Pointer to the data buffer where data is to be copied. 364 * \return Returns the number of bytes copied to the buffer. 365 */ 366 uint32_t (*ReadSetupPkt)(USBD_HANDLE_T hUsb, uint32_t EPNum, uint32_t *pData); 367 368 /** \fn uint32_t WriteEP(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData, uint32_t cnt) 369 * Function to write data to be sent on the requested endpoint. 370 * 371 * This function is called by USB stack and the application layer to send data 372 * on the requested endpoint. 373 * 374 * \param[in] hUsb Handle to the USB device stack. 375 * \param[in] EPNum Endpoint number as per USB specification. 376 * ie. An EP1_IN is represented by 0x81 number. 377 * \param[in] pData Pointer to the data buffer from where data is to be copied. 378 * \param[in] cnt Number of bytes to write. 379 * \return Returns the number of bytes written. 380 */ 381 uint32_t (*WriteEP)(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData, uint32_t cnt); 382 383 /** \fn void WakeUp(USBD_HANDLE_T hUsb) 384 * Function to generate resume signaling on bus for remote host wakeup. 385 * 386 * This function is called by application layer to remotely wakeup host controller 387 * when system is in suspend state. Application should indicate this remote wakeup 388 * capability by setting USB_CONFIG_REMOTE_WAKEUP in bmAttributes of Configuration 389 * Descriptor. Also this routine will generate resume signalling only if host 390 * enables USB_FEATURE_REMOTE_WAKEUP by sending SET_FEATURE request before suspending 391 * the bus. 392 * 393 * \param[in] hUsb Handle to the USB device stack. 394 * \return Nothing. 395 */ 396 void (*WakeUp)(USBD_HANDLE_T hUsb); 397 398 /** \fn void EnableEvent(USBD_HANDLE_T hUsb, uint32_t EPNum, uint32_t event_type, uint32_t enable) 399 * Function to enable/disable selected USB event. 400 * 401 * This function enables interrupts on selected endpoint. 402 * 403 * \param[in] hUsb Handle to the USB device stack. 404 * \param[in] EPNum Endpoint number corresponding to the event. 405 * ie. An EP1_IN is represented by 0x81 number. For device events 406 * set this param to 0x0. 407 * \param[in] event_type Type of endpoint event. See \ref USBD_EVENT_T for more details. 408 * \param[in] enable 1 - enable event, 0 - disable event. 409 * \return Returns \ref ErrorCode_t type to indicate success or error condition. 410 * \retval LPC_OK(0) - On success 411 * \retval ERR_USBD_INVALID_REQ(0x00040001) - Invalid event type. 412 */ 413 ErrorCode_t (*EnableEvent)(USBD_HANDLE_T hUsb, uint32_t EPNum, uint32_t event_type, uint32_t enable); 414 415 } USBD_HW_API_T; 416 417 /*----------------------------------------------------------------------------- 418 * Private functions & structures prototypes used by stack internally 419 *-----------------------------------------------------------------------------*/ 420 /** @cond DIRECT_API */ 421 422 /* Driver functions */ 423 uint32_t hwUSB_GetMemSize(USBD_API_INIT_PARAM_T* param); 424 ErrorCode_t hwUSB_Init(USBD_HANDLE_T* phUsb, USB_CORE_DESCS_T* pDesc, USBD_API_INIT_PARAM_T* param); 425 void hwUSB_Connect(USBD_HANDLE_T hUsb, uint32_t con); 426 void hwUSB_ISR(USBD_HANDLE_T hUsb); 427 428 /* USB Hardware Functions */ 429 extern void hwUSB_Reset(USBD_HANDLE_T hUsb); 430 extern void hwUSB_ForceFullSpeed (USBD_HANDLE_T hUsb, uint32_t con); 431 extern void hwUSB_WakeUpCfg(USBD_HANDLE_T hUsb, uint32_t cfg); 432 extern void hwUSB_SetAddress(USBD_HANDLE_T hUsb, uint32_t adr); 433 extern void hwUSB_Configure(USBD_HANDLE_T hUsb, uint32_t cfg); 434 extern void hwUSB_ConfigEP(USBD_HANDLE_T hUsb, USB_ENDPOINT_DESCRIPTOR *pEPD); 435 extern void hwUSB_DirCtrlEP(USBD_HANDLE_T hUsb, uint32_t dir); 436 extern void hwUSB_EnableEP(USBD_HANDLE_T hUsb, uint32_t EPNum); 437 extern void hwUSB_DisableEP(USBD_HANDLE_T hUsb, uint32_t EPNum); 438 extern void hwUSB_ResetEP(USBD_HANDLE_T hUsb, uint32_t EPNum); 439 extern void hwUSB_SetStallEP(USBD_HANDLE_T hUsb, uint32_t EPNum); 440 extern void hwUSB_ClrStallEP(USBD_HANDLE_T hUsb, uint32_t EPNum); 441 extern ErrorCode_t hwUSB_SetTestMode(USBD_HANDLE_T hUsb, uint8_t mode); /* for FS only devices return ERR_USBD_INVALID_REQ */ 442 extern uint32_t hwUSB_ReadEP(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData); 443 extern uint32_t hwUSB_ReadReqEP(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData, uint32_t len); 444 extern uint32_t hwUSB_ReadSetupPkt(USBD_HANDLE_T hUsb, uint32_t, uint32_t *); 445 extern uint32_t hwUSB_WriteEP(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData, uint32_t cnt); 446 447 /* generate resume signaling on the bus */ 448 extern void hwUSB_WakeUp(USBD_HANDLE_T hUsb); 449 extern ErrorCode_t hwUSB_EnableEvent(USBD_HANDLE_T hUsb, uint32_t EPNum, uint32_t event_type, uint32_t enable); 450 /* TODO implement following routines 451 - function to program TD and queue them to ep Qh 452 */ 453 454 /** @endcond */ 455 456 457 #endif /* __USBHW_H__ */ 458