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_NACKED   (1<<3)
#define	EP_STATUS_ERROR   (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)
BOOL	USBHwEPIsStalled (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

(c) 2006, Bertrik Sikken, bertrik@sikken.nl

---

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<<4)

EP data was overwritten by setup packet

#define EP_STATUS_NACKED   (1<<3)

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

BOOL USBHwEPIsStalled (  U8  bEP  )

Gets the stalled property of an endpoint Parameters: [in]  bEP  Endpoint number Returns: TRUE if stalled, FALSE if not stalled

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 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

---