- Main Page
- Classes
- Files
- Related Pages

- File List
- File Members

# usbapi.h File Reference

`#include "type.h"`
`#include "usbstruct.h"`

Include dependency graph for usbapi.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Defines

#define | MAX_PACKET_SIZE0 64
#define | EP_STATUS_DATA (1<<0)
#define | EP_STATUS_STALLED (1<<1)
#define | EP_STATUS_SETUP (1<<2)
#define | EP_STATUS_ERROR (1<<3)
#define | EP_STATUS_NACKED (1<<4)
#define | DEV_STATUS_CONNECT (1<<0)
#define | DEV_STATUS_SUSPEND (1<<2)
#define | DEV_STATUS_RESET (1<<4)
#define | INACK_CI (1<<1)
#define | INACK_CO (1<<2)
#define | INACK_II (1<<3)
#define | INACK_IO (1<<4)
#define | INACK_BI (1<<5)
#define | INACK_BO (1<<6)

## Typedefs

typedef void( | TFnEPIntHandler )(U8 bEP, U8 bEPStatus)
typedef void( | TFnDevIntHandler )(U8 bDevStatus)
typedef void( | TFnFrameHandler )(U16 wFrame)
typedef BOOL( | TFnHandleRequest )(TSetupPacket *pSetup, int *piLen, U8 **ppbData)
typedef BOOL( | TFnGetDescriptor )(U16 wTypeIndex, U16 wLangID, int *piLen, U8 **ppbData)

## Functions

BOOL | USBHwInit (void)
void | USBHwISR (void)
void | USBHwNakIntEnable (U8 bIntBits)
void | USBHwConnect (BOOL fConnect)
void | USBHwSetAddress (U8 bAddr)
void | USBHwConfigDevice (BOOL fConfigured)
void | USBHwEPConfig (U8 bEP, U16 wMaxPacketSize)
int | USBHwEPRead (U8 bEP, U8 *pbBuf, int iMaxLen)
int | USBHwEPWrite (U8 bEP, U8 *pbBuf, int iLen)
void | USBHwEPStall (U8 bEP, BOOL fStall)
U8 | USBHwEPGetStatus (U8 bEP)
void | USBHwRegisterEPIntHandler (U8 bEP, TFnEPIntHandler *pfnHandler)
void | USBHwRegisterDevIntHandler (TFnDevIntHandler *pfnHandler)
void | USBHwRegisterFrameHandler (TFnFrameHandler *pfnHandler)
BOOL | USBInit (void)
void | USBRegisterRequestHandler (int iType, TFnHandleRequest *pfnHandler, U8 *pbDataStore)
void | USBRegisterCustomReqHandler (TFnHandleRequest *pfnHandler)
BOOL | USBHandleStandardRequest (TSetupPacket *pSetup, int *piLen, U8 **ppbData)
void | USBHandleControlTransfer (U8 bEP, U8 bEPStat)
void | USBRegisterDescriptors (const U8 *pabDescriptors)
BOOL | USBGetDescriptor (U16 wTypeIndex, U16 wLangID, int *piLen, U8 **ppbData)

## Detailed Description

## Define Documentation

#define DEV_STATUS_CONNECT (1<<0)

device just got connected

#define DEV_STATUS_RESET (1<<4)

device just got reset

#define DEV_STATUS_SUSPEND (1<<2)

device entered suspend state

#define EP_STATUS_DATA (1<<0)

EP has data

#define EP_STATUS_ERROR (1<<3)

EP data was overwritten by setup packet

#define EP_STATUS_NACKED (1<<4)

EP sent NAK

#define EP_STATUS_SETUP (1<<2)

EP received setup packet

#define EP_STATUS_STALLED (1<<1)

EP is stalled

#define INACK_BI (1<<5)

interrupt on NACK for bulk in

#define INACK_BO (1<<6)

interrupt on NACK for bulk out

#define INACK_CI (1<<1)

interrupt on NACK for control in

#define INACK_CO (1<<2)

interrupt on NACK for control out

#define INACK_II (1<<3)

interrupt on NACK for interrupt in

#define INACK_IO (1<<4)

interrupt on NACK for interrupt out

#define MAX_PACKET_SIZE0 64

maximum packet size for EP 0

## Typedef Documentation

typedef void( TFnDevIntHandler)(U8 bDevStatus)

Device status handler callback

typedef void( TFnEPIntHandler)(U8 bEP, U8 bEPStatus)

Endpoint interrupt handler callback

typedef void( TFnFrameHandler)(U16 wFrame)

Frame event handler callback

typedef BOOL( TFnGetDescriptor)(U16 wTypeIndex, U16 wLangID, int *piLen, U8 **ppbData)

Descriptor handler callback

typedef BOOL( TFnHandleRequest)(TSetupPacket *pSetup, int *piLen, U8 **ppbData)

Request handler callback (standard, vendor, class)

## Function Documentation

BOOL USBGetDescriptor | ( | U16 | wTypeIndex,
|  | U16 | wLangID,
|  | int * | piLen,
|  | U8 ** | ppbData |
| ) |  |  |

Parses the list of installed USB descriptors and attempts to find the specified USB descriptor.

Parameters:

  `[in]` | wTypeIndex | Type and index of the descriptor
  `[in]` | wLangID | Language ID of the descriptor (currently unused)
  `[out]` | *piLen | Descriptor length
  `[out]` | *ppbData | Descriptor data

Returns:
  TRUE if the descriptor was found, FALSE otherwise

void USBHandleControlTransfer | ( | U8 | bEP,
|  | U8 | bEPStat |
| ) |  |  |

Handles IN/OUT transfers on EP0

Parameters:

  `[in]` | bEP | Endpoint address
  `[in]` | bEPStat | Endpoint status

BOOL USBHandleStandardRequest | ( | TSetupPacket * | pSetup,
|  | int * | piLen,
|  | U8 ** | ppbData |
| ) |  |  |

Default handler for standard ('chapter 9') requests

If a custom request handler was installed, this handler is called first.

Parameters:

  `[in]` | pSetup | The setup packet
  `[in,out]` | *piLen | Pointer to data length
  `[in]` | ppbData | Data buffer.

Returns:
  TRUE if the request was handled successfully

void USBHwConfigDevice | ( | BOOL | fConfigured | ) |

Sets the 'configured' state.

All registered endpoints are 'realised' and enabled, and the 'configured' bit is set in the device status register.

Parameters:

  `[in]` | fConfigured | If TRUE, configure device, else unconfigure

void USBHwConnect | ( | BOOL | fConnect | ) |

Connects or disconnects from the USB bus

Parameters:

  `[in]` | fConnect | If TRUE, connect, otherwise disconnect

void USBHwEPConfig | ( | U8 | bEP,
|  | U16 | wMaxPacketSize |
| ) |  |  |

Configures an endpoint and enables it

Parameters:

  `[in]` | bEP | Endpoint number
  `[in]` | wMaxPacketSize | Maximum packet size for this EP

U8 USBHwEPGetStatus | ( | U8 | bEP | ) |

Gets the status from a specific endpoint.

Parameters:

  `[in]` | bEP | Endpoint number

Returns:
  Endpoint status byte (containing EP_STATUS_xxx bits)

int USBHwEPRead | ( | U8 | bEP,
|  | U8 * | pbBuf,
|  | int | iMaxLen |
| ) |  |  |

Reads data from an endpoint buffer

Parameters:

  `[in]` | bEP | Endpoint number
  `[in]` | pbBuf | Endpoint data
  `[in]` | iMaxLen | Maximum number of bytes to read

Returns:
  the number of bytes available in the EP (possibly more than iMaxLen), or <0 in case of error.

void USBHwEPStall | ( | U8 | bEP,
|  | BOOL | fStall |
| ) |  |  |

Sets the stalled property of an endpoint

Parameters:

  `[in]` | bEP | Endpoint number
  `[in]` | fStall | TRUE to stall, FALSE to unstall

int USBHwEPWrite | ( | U8 | bEP,
|  | U8 * | pbBuf,
|  | int | iLen |
| ) |  |  |

Writes data to an endpoint buffer

Parameters:

  `[in]` | bEP | Endpoint number
  `[in]` | pbBuf | Endpoint data
  `[in]` | iLen | Number of bytes to write

Returns:
  TRUE if the data was successfully written or <0 in case of error.

BOOL USBHwInit | ( | void |  | ) |

Initialises the USB hardware

This function assumes that the hardware is connected as shown in section 10.1 of the LPC2148 data sheet: P0.31 controls a switch to connect a 1.5k pull-up to D+ if low. P0.23 is connected to USB VCC.

Embedded artists board: make sure to disconnect P0.23 LED as it acts as a pull-up and so prevents detection of USB disconnect.

Returns:
  TRUE if the hardware was successfully initialised

void USBHwISR | ( | void |  | ) |

USB interrupt handler

Todo:
  Get all 11 bits of frame number instead of just 8

Endpoint interrupts are mapped to the slow interrupt

void USBHwNakIntEnable | ( | U8 | bIntBits | ) |

Enables interrupt on NAK condition

For IN endpoints a NAK is generated when the host wants to read data from the device, but none is available in the endpoint buffer. For OUT endpoints a NAK is generated when the host wants to write data to the device, but the endpoint buffer is still full.

The endpoint interrupt handlers can distinguish regular (ACK) interrupts from NAK interrupt by checking the bits in their bEPStatus argument.

Parameters:

  `[in]` | bIntBits | Bitmap indicating which NAK interrupts to enable

void USBHwRegisterDevIntHandler | ( | TFnDevIntHandler * | pfnHandler | ) |

Registers an device status callback

Parameters:

  `[in]` | pfnHandler | Callback function

void USBHwRegisterEPIntHandler | ( | U8 | bEP,
|  | TFnEPIntHandler * | pfnHandler |
| ) |  |  |

Registers an endpoint event callback

Parameters:

  `[in]` | bEP | Endpoint number
  `[in]` | pfnHandler | Callback function

void USBHwRegisterFrameHandler | ( | TFnFrameHandler * | pfnHandler | ) |

Registers the frame callback

Parameters:

  `[in]` | pfnHandler | Callback function

void USBHwSetAddress | ( | U8 | bAddr | ) |

Sets the USB address.

Parameters:

  `[in]` | bAddr | Device address to set

BOOL USBInit | ( | void |  | ) |

Initialises the USB hardware and sets up the USB stack by installing default callbacks.

Returns:
  TRUE if initialisation was successful

void USBRegisterCustomReqHandler | ( | TFnHandleRequest * | pfnHandler | ) |

Registers a callback for custom device requests

In USBHandleStandardRequest, the custom request handler gets a first chance at handling the request before it is handed over to the 'chapter 9' request handler.

This can be used for example in HID devices, where a REQ_GET_DESCRIPTOR request is sent to an interface, which is not covered by the 'chapter 9' specification.

Parameters:

  `[in]` | pfnHandler | Callback function pointer

void USBRegisterDescriptors | ( | const U8 * | pabDescriptors | ) |

Registers a pointer to a descriptor block containing all descriptors for the device.

Parameters:

  `[in]` | pabDescriptors | The descriptor byte array

void USBRegisterRequestHandler | ( | int | iType,
|  | TFnHandleRequest * | pfnHandler,
|  | U8 * | pbDataStore |
| ) |  |  |

Registers a callback for handling requests

Parameters:

  `[in]` | iType | Type of request, e.g. REQTYPE_TYPE_STANDARD
  `[in]` | *pfnHandler | Callback function pointer
  `[in]` | *pbDataStore | Data storage area for this type of request