USBD ROM Stack  1.0
ROM based USB device stack
USBD_HW_API_T Struct Reference

Hardware API functions structure.This module exposes functions which interact directly with USB device controller hardware. More...

#include <mw_usbd/mw_usbd_hw.h>

Data Fields

uint32_t(* GetMemSize )(USBD_API_INIT_PARAM_T *param)
ErrorCode_t(* Init )(USBD_HANDLE_T *phUsb, USB_CORE_DESCS_T *pDesc, USBD_API_INIT_PARAM_T *param)
void(* Connect )(USBD_HANDLE_T hUsb, uint32_t con)
void(* ISR )(USBD_HANDLE_T hUsb)
void(* Reset )(USBD_HANDLE_T hUsb)
void(* ForceFullSpeed )(USBD_HANDLE_T hUsb, uint32_t cfg)
void(* WakeUpCfg )(USBD_HANDLE_T hUsb, uint32_t cfg)
void(* SetAddress )(USBD_HANDLE_T hUsb, uint32_t adr)
void(* Configure )(USBD_HANDLE_T hUsb, uint32_t cfg)
void(* ConfigEP )(USBD_HANDLE_T hUsb, USB_ENDPOINT_DESCRIPTOR *pEPD)
void(* DirCtrlEP )(USBD_HANDLE_T hUsb, uint32_t dir)
void(* EnableEP )(USBD_HANDLE_T hUsb, uint32_t EPNum)
void(* DisableEP )(USBD_HANDLE_T hUsb, uint32_t EPNum)
void(* ResetEP )(USBD_HANDLE_T hUsb, uint32_t EPNum)
void(* SetStallEP )(USBD_HANDLE_T hUsb, uint32_t EPNum)
void(* ClrStallEP )(USBD_HANDLE_T hUsb, uint32_t EPNum)
ErrorCode_t(* SetTestMode )(USBD_HANDLE_T hUsb, uint8_t mode)
uint32_t(* ReadEP )(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData)
uint32_t(* ReadReqEP )(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData, uint32_t len)
uint32_t(* ReadSetupPkt )(USBD_HANDLE_T hUsb, uint32_t EPNum, uint32_t *pData)
uint32_t(* WriteEP )(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData, uint32_t cnt)
void(* WakeUp )(USBD_HANDLE_T hUsb)
ErrorCode_t(* EnableEvent )(USBD_HANDLE_T hUsb, uint32_t EPNum, uint32_t event_type, uint32_t enable)

Detailed Description

Hardware API functions structure.

This module exposes functions which interact directly with USB device controller hardware.


Field Documentation

Function to determine the memory required by the USB device stack's DCD and core layers.

This function is called by application layer before calling pUsbApi->hw->Init(), to allocate memory used by DCD and core layers. The application should allocate the memory which is accessible by USB controller/DMA controller.

Note:
Some memory areas are not accessible by all bus masters.
Parameters:
[in]paramStructure containing USB device stack initialization parameters.
Returns:
Returns the required memory size in bytes.

Function to initialize USB device stack's DCD and core layers.

This function is called by application layer to initialize USB hardware and core layers. On successful initialization the function returns a handle to USB device stack which should be passed to the rest of the functions.

Parameters:
[in,out]phUsbPointer to the USB device stack handle of type USBD_HANDLE_T.
[in]pDescStructure containing pointers to various descriptor arrays needed by the stack. These descriptors are reported to USB host as part of enumerations process.
[in]paramStructure containing USB device stack initialization parameters.
Returns:
Returns ErrorCode_t type to indicate success or error condition.
Return values:
LPC_OK(0)On success
ERR_USBD_BAD_MEM_BUF(0x0004000b)When insufficient memory buffer is passed or memory is not aligned on 2048 boundary.

Function to make USB device visible/invisible on the USB bus.

This function is called after the USB initialization. This function uses the soft connect feature to make the device visible on the USB bus. This function is called only after the application is ready to handle the USB data. The enumeration process is started by the host after the device detection. The driver handles the enumeration process according to the USB descriptors passed in the USB initialization function.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]conStates whether to connect (1) or to disconnect (0).
Returns:
Nothing.

Function to USB device controller interrupt events.

When the user application is active the interrupt handlers are mapped in the user flash space. The user application must provide an interrupt handler for the USB interrupt and call this function in the interrupt handler routine. The driver interrupt handler takes appropriate action according to the data received on the USB bus.

Parameters:
[in]hUsbHandle to the USB device stack.
Returns:
Nothing.

Function to Reset USB device stack and hardware controller.

Reset USB device stack and hardware controller. Disables all endpoints except EP0. Clears all pending interrupts and resets endpoint transfer queues. This function is called internally by pUsbApi->hw->init() and from reset event.

Parameters:
[in]hUsbHandle to the USB device stack.
Returns:
Nothing.

Function to force high speed USB device to operate in full speed mode.

This function is useful for testing the behavior of current device when connected to a full speed only hosts.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]cfgWhen 1 - set force full-speed or 0 - clear force full-speed.
Returns:
Nothing.

Function to configure USB device controller to wake-up host on remote events.

This function is called by application layer to configure the USB device controller to wakeup on remote events. It is recommended to call this function from users's USB_WakeUpCfg() callback routine registered with stack.

Note:
User's USB_WakeUpCfg() is registered with stack by setting the USB_WakeUpCfg member of USBD_API_INIT_PARAM_T structure before calling pUsbApi->hw->Init() routine. Certain USB device controllers needed to keep some clocks always on to generate resume signaling through pUsbApi->hw->WakeUp(). This hook is provided to support such controllers. In most controllers cases this is an empty routine.
Parameters:
[in]hUsbHandle to the USB device stack.
[in]cfgWhen 1 - Configure controller to wake on remote events or 0 - Configure controller not to wake on remote events.
Returns:
Nothing.

Function to set USB address assigned by host in device controller hardware.

This function is called automatically when USB_REQUEST_SET_ADDRESS request is received by the stack from USB host. This interface is provided to users to invoke this function in other scenarios which are not handle by current stack. In most user applications this function is not called directly. Also this function can be used by users who are selectively modifying the USB device stack's standard handlers through callback interface exposed by the stack.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]adrUSB bus Address to which the device controller should respond. Usually assigned by the USB host.
Returns:
Nothing.

Function to configure device controller hardware with selected configuration.

This function is called automatically when USB_REQUEST_SET_CONFIGURATION request is received by the stack from USB host. This interface is provided to users to invoke this function in other scenarios which are not handle by current stack. In most user applications this function is not called directly. Also this function can be used by users who are selectively modifying the USB device stack's standard handlers through callback interface exposed by the stack.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]cfgConfiguration index.
Returns:
Nothing.

Function to configure USB Endpoint according to descriptor.

This function is called automatically when USB_REQUEST_SET_CONFIGURATION request is received by the stack from USB host. All the endpoints associated with the selected configuration are configured. This interface is provided to users to invoke this function in other scenarios which are not handle by current stack. In most user applications this function is not called directly. Also this function can be used by users who are selectively modifying the USB device stack's standard handlers through callback interface exposed by the stack.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]pEPDEndpoint descriptor structure defined in USB 2.0 specification.
Returns:
Nothing.

Function to set direction for USB control endpoint EP0.

This function is called automatically by the stack on need basis. This interface is provided to users to invoke this function in other scenarios which are not handle by current stack. In most user applications this function is not called directly. Also this function can be used by users who are selectively modifying the USB device stack's standard handlers through callback interface exposed by the stack.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]cfgWhen 1 - Set EP0 in IN transfer mode 0 - Set EP0 in OUT transfer mode
Returns:
Nothing.

Function to enable selected USB endpoint.

This function enables interrupts on selected endpoint.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]EPNumEndpoint number as per USB specification. ie. An EP1_IN is represented by 0x81 number.
Returns:
Nothing.

Function to disable selected USB endpoint.

This function disables interrupts on selected endpoint.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]EPNumEndpoint number as per USB specification. ie. An EP1_IN is represented by 0x81 number.
Returns:
Nothing.

Function to reset selected USB endpoint.

This function flushes the endpoint buffers and resets data toggle logic.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]EPNumEndpoint number as per USB specification. ie. An EP1_IN is represented by 0x81 number.
Returns:
Nothing.

Function to STALL selected USB endpoint.

Generates STALL signaling for requested endpoint.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]EPNumEndpoint number as per USB specification. ie. An EP1_IN is represented by 0x81 number.
Returns:
Nothing.

Function to clear STALL state for the requested endpoint.

This function clears STALL state for the requested endpoint.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]EPNumEndpoint number as per USB specification. ie. An EP1_IN is represented by 0x81 number.
Returns:
Nothing.

Function to set high speed USB device controller in requested test mode.

USB-IF requires the high speed device to be put in various test modes for electrical testing. This USB device stack calls this function whenever it receives USB_REQUEST_CLEAR_FEATURE request for USB_FEATURE_TEST_MODE. Users can put the device in test mode by directly calling this function. Returns ERR_USBD_INVALID_REQ when device controller is full-speed only.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]modeTest mode defined in USB 2.0 electrical testing specification.
Returns:
Returns ErrorCode_t type to indicate success or error condition.
Return values:
LPC_OK(0)- On success
ERR_USBD_INVALID_REQ(0x00040001)- Invalid test mode or Device controller is full-speed only.

Function to read data received on the requested endpoint.

This function is called by USB stack and the application layer to read the data received on the requested endpoint.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]EPNumEndpoint number as per USB specification. ie. An EP1_IN is represented by 0x81 number.
[in,out]pDataPointer to the data buffer where data is to be copied.
Returns:
Returns the number of bytes copied to the buffer.

Function to queue read request on the specified endpoint.

This function is called by USB stack and the application layer to queue a read request on the specified endpoint.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]EPNumEndpoint number as per USB specification. ie. An EP1_IN is represented by 0x81 number.
[in,out]pDataPointer to the data buffer where data is to be copied. This buffer address should be accessible by USB DMA master.
[in]lenLength of the buffer passed.
Returns:
Returns the length of the requested buffer.

Function to read setup packet data received on the requested endpoint.

This function is called by USB stack and the application layer to read setup packet data received on the requested endpoint.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]EPNumEndpoint number as per USB specification. ie. An EP0_IN is represented by 0x80 number.
[in,out]pDataPointer to the data buffer where data is to be copied.
Returns:
Returns the number of bytes copied to the buffer.

Function to write data to be sent on the requested endpoint.

This function is called by USB stack and the application layer to send data on the requested endpoint.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]EPNumEndpoint number as per USB specification. ie. An EP1_IN is represented by 0x81 number.
[in]pDataPointer to the data buffer from where data is to be copied.
[in]cntNumber of bytes to write.
Returns:
Returns the number of bytes written.

Function to generate resume signaling on bus for remote host wakeup.

This function is called by application layer to remotely wakeup host controller when system is in suspend state. Application should indicate this remote wakeup capability by setting USB_CONFIG_REMOTE_WAKEUP in bmAttributes of Configuration Descriptor. Also this routine will generate resume signalling only if host enables USB_FEATURE_REMOTE_WAKEUP by sending SET_FEATURE request before suspending the bus.

Parameters:
[in]hUsbHandle to the USB device stack.
Returns:
Nothing.

Function to enable/disable selected USB event.

This function enables interrupts on selected endpoint.

Parameters:
[in]hUsbHandle to the USB device stack.
[in]EPNumEndpoint number corresponding to the event. ie. An EP1_IN is represented by 0x81 number. For device events set this param to 0x0.
[in]event_typeType of endpoint event. See USBD_EVENT_T for more details.
[in]enable1 - enable event, 0 - disable event.
Returns:
Returns ErrorCode_t type to indicate success or error condition.
Return values:
LPC_OK(0)- On success
ERR_USBD_INVALID_REQ(0x00040001)- Invalid event type.

The documentation for this struct was generated from the following file: