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