usb.h

AT91SAM9261的USB设备驱动程序

static inline void USB_NewRequestCallback(const S_usb *pUsb)
{
    if (pUsb->pCallbacks->newRequest != 0) {

        pUsb->pCallbacks->newRequest(pUsb);
    }
}

// Invokes the SOF callback if it exists
static inline void USB_StartOfFrameCallback(const S_usb *pUsb)
{
    pUsb->pCallbacks->startOfFrame(pUsb);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Sends data through an USB endpoint.
//!
//! This function sends the specified amount of data through a particular
//! endpoint. The transfer finishes either when the data has been completely
//! sent, or an abnormal condition causes the API to abort this operation.
//! An optional user-provided callback can be invoked once the transfer is
//! complete.\n
//! On control endpoints, this function automatically send a Zero-Length Packet
//! (ZLP) if the data payload size is a multiple of the endpoint maximum packet
//! size. This is not the case for bulk, interrupt or isochronous endpoints.
//! \param  pUsb      Pointer to a S_usb instance
//! \param  bEndpoint Number of the endpoint through which to send the data
//! \param  pData     Pointer to a buffer containing the data to send
//! \param  dLength   Size of the data buffer
//! \param  fCallback Callback function to invoke when the transfer finishes
//! \param  pArgument Optional parameter to pass to the callback function
//! \return Result of operation
//! \see    usb_api_ret_val
//! \see    S_usb
//------------------------------------------------------------------------------
inline char USB_Write(const S_usb *pUsb,
                      unsigned char bEndpoint,
                      const void *pData,
                      unsigned int dLength,
                      Callback_f fCallback,
                      void *pArgument)
{
    return pUsb->pDriver->pMethods->write(pUsb,
                                          bEndpoint,
                                          pData,
                                          dLength,
                                          fCallback,
                                          pArgument);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Sends a Zero-Length Packet (ZLP) through the Control endpoint 0.
//!
//! Since sending a ZLP on endpoint 0 is quite common, this function is provided
//! as an overload to the USB_Write function.
//! \param  pUsb      Pointer to a S_usb instance
//! \param  fCallback Optional callback function to invoke when the transfer
//!                   finishes
//! \param  pArgument Optional parameter to pass to the callback function
//! \return Result of operation
//! \see    USB_Write
//! \see    usb_api_ret_val
//! \see    S_usb
//------------------------------------------------------------------------------
inline char USB_SendZLP0(const S_usb *pUsb,
                         Callback_f  fCallback,
                         void        *pArgument) {

    return USB_Write(pUsb, 0, 0, 0, fCallback, pArgument);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Receives data on the specified USB endpoint.
//!
//! This functions receives data on a particular endpoint. It finishes either
//! when the provided buffer is full, when a short packet (payload size inferior
//! to the endpoint maximum packet size) is received, or if an abnormal
//! condition causes a transfer abort. An optional user-provided callback can be
//! invoked upon the transfer completion
//! \param  pUsb      Pointer to a S_usb instance
//! \param  bEndpoint Number of the endpoint on which to receive the data
//! \param  pData     Pointer to the buffer in which to store the received data
//! \param  dLength   Size of the receive buffer
//! \param  fCallback Optional user-provided callback function invoked upon the
//!                   transfer completion
//! \param  pArgument Optional parameter to pass to the callback function
//! \return Result of operation
//! \see    usb_api_ret_val
//! \see    S_usb
//------------------------------------------------------------------------------
inline char USB_Read(const S_usb *pUsb,
                     unsigned char bEndpoint,
                     void *pData,
                     unsigned int dLength,
                     Callback_f fCallback,
                     void *pArgument)
{
    return pUsb->pDriver->pMethods->read(pUsb,
                                         bEndpoint,
                                         pData,
                                         dLength,
                                         fCallback,
                                         pArgument);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Sends a STALL handshake for the next received packet.
//!
//! This function only send one STALL handshake, and only if the next packet
//! is not a SETUP packet (when using this function on a control endpoint).
//! \param  pUsb      Pointer to a S_usb instance
//! \param  bEndpoint Number of endpoint on which to send the STALL
//! \return Result of operation
//! \see    usb_api_ret_val
//! \see    USB_Halt
//! \see    S_usb
//------------------------------------------------------------------------------
inline char USB_Stall(const S_usb *pUsb, unsigned char bEndpoint)
{
    return pUsb->pDriver->pMethods->stall(pUsb, bEndpoint);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Starts a remote wakeup procedure
//! \param  pUsb Pointer to a S_usb instance
//! \see    S_usb
//------------------------------------------------------------------------------
inline void USB_RemoteWakeUp(const S_usb *pUsb)
{
    pUsb->pDriver->pMethods->remoteWakeUp(pUsb);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Clears, sets or retrieves the halt state of the specified endpoint.
//!
//! While an endpoint is in Halt state, it acknowledges every received packet
//! with a STALL handshake.
//! \param  pUsb      Pointer to a S_usb instance
//! \param  bEndpoint Number of the endpoint to alter
//! \param  bRequest  The operation to perform (set, clear or get)
//! \return true if the endpoint is halted, false otherwise
//! \see    S_usb
//------------------------------------------------------------------------------
inline bool USB_Halt(const S_usb   *pUsb,
                     unsigned char bEndpoint,
                     unsigned char bRequest)
{
    return pUsb->pDriver->pMethods->halt(pUsb,
                                         (unsigned char)(bEndpoint&0x7F),
                                         bRequest);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Sets the device address using the last received SETUP packet.
//!
//! This method must only be called after a SET_ADDRESS standard request has
//! been received. This is because it uses the last received SETUP packet stored
//! in the S_usb structure to determine which address the device should use.
//! \param  pUsb Pointer to a S_usb instance
//! \see    std_dev_req
//! \see    S_usb
//------------------------------------------------------------------------------
inline void USB_SetAddress(const S_usb *pUsb)
{
    pUsb->pDriver->pMethods->setAddress(pUsb);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Sets the device configuration using the last received SETUP packet.
//!
//! This method must only be called after a SET_CONFIGURATION standard request
//! has been received. This is necessary because it uses the last received
//! SETUP packet (stored in the S_usb structure) to determine which
//! configuration it should adopt.
//! \param  pUsb Pointer to a S_usb instance
//! \see    std_dev_req
//! \see    S_usb
//------------------------------------------------------------------------------
inline void USB_SetConfiguration(const S_usb *pUsb)
{
    pUsb->pDriver->pMethods->setConfiguration(pUsb);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Configures the specified endpoint using the provided endpoint
//!         descriptor.
//!
//! An endpoint must be configured prior to being used. This is not necessary
//! for control endpoint 0, as this operation is automatically performed during
//! initialization.
//! \param  pUsb    Pointer to a S_usb instance
//! \param  pEpDesc Pointer to an endpoint descriptor
//! \return true if the endpoint has been configured, false otherwise
//! \see    S_usb_endpoint_descriptor
//! \see    S_usb
//------------------------------------------------------------------------------
inline bool USB_ConfigureEndpoint(const S_usb                     *pUsb,
                                  const S_usb_endpoint_descriptor *pEpDesc)
{
    return pUsb->pDriver->pMethods->configureEndpoint(pUsb, pEpDesc);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Event handler for the USB controller peripheral.
//!
//! This function handles low-level events comming from the USB controller
//! peripheral. It then dispatches those events through the user-provided
//! callbacks. The following callbacks can be triggered:
//! \li S_usb_reset
//! \li S_usb_suspend
//! \li S_usb_resume
//! \li S_usb_new_request
//! \param  pUsb Pointer to a S_usb instance
//! \see    usb_api_callbacks
//! \see    S_usb_callbacks
//! \see    S_usb
//------------------------------------------------------------------------------
inline void USB_Handler(const S_usb * pUsb)
{
    pUsb->pDriver->pMethods->handler(pUsb);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Handles the attachment or detachment of the device to or from the
//!         USB
//!
//! This method should be called whenever the VBus power line changes state,
//! i.e. the device becomes powered/unpowered. Alternatively, it can also be
//! called to poll the status of the device.\n
//! When the device is detached from the bus, the S_usb_suspend callback is
//! invoked. Conversely, when the device is attached, the S_usb_resume callback
//! is triggered.
//! \param  pUsb Pointer to a S_usb instance
//! \return true if the device is currently attached, false otherwise
//! \see    S_usb_suspend
//! \see    S_usb_resume
//! \see    usb_api_callbacks
//! \see    S_usb
//------------------------------------------------------------------------------
inline bool USB_Attach(const S_usb *pUsb)
{
    return pUsb->pDriver->pMethods->attach(pUsb);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Connects the device to the USB.
//!
//! This method enables the pull-up resistor on the D+ line, notifying the host
//! that the device wishes to connect to the bus.
//! \param  pUsb Pointer to a S_usb instance
//! \see    USB_Disconnect
//------------------------------------------------------------------------------
inline void USB_Connect(const S_usb *pUsb)
{
    pUsb->pDriver->pMethods->connect(pUsb);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Disconnects the device from the USB.
//!
//! This method disables the pull-up resistor on the D+ line, notifying the host
//! that the device wishes to disconnect from the bus.
//! \param  pUsb Pointer to a S_usb instance
//! \see    USB_Connect
//------------------------------------------------------------------------------
inline void USB_Disconnect(const S_usb *pUsb)
{
    pUsb->pDriver->pMethods->disconnect(pUsb);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Initializes the USB API and the USB controller.
//!
//! This method must be called prior to using an other USB method. Before
//! finishing, it invokes the S_usb_init callback.
//! \param  pUsb Pointer to a S_usb instance
//! \see    S_usb_init
//! \see    S_usb
//------------------------------------------------------------------------------
inline void USB_Init(const S_usb *pUsb)
{
    pUsb->pDriver->pMethods->init(pUsb);
}

//------------------------------------------------------------------------------
//! \ingroup usb_api_methods
//! \brief  Returns the current state of the device.
//! \param  pUsb Pointer to a S_usb instance
//! \return Current state of the device
//! \see    S_usb
//------------------------------------------------------------------------------
inline unsigned int USB_GetState(const S_usb *pUsb)
{
    return (*(pUsb->pState) & 0x0000FFFF);
}

//------------------------------------------------------------------------------
//      Exports
//------------------------------------------------------------------------------

//------------------------------------------------------------------------------
//! \ingroup  usb_api_struct
//! \defgroup usb_api_global Global variables
//! \brief  Several global variables are exported by the USB API to be used in
//!         user programs.
//! @{
//------------------------------------------------------------------------------

//! \brief  Global variable holding the methods used by an UDP controller
//! \see    S_driver_methods
//! \see    S_usb_driver
extern const S_driver_methods sUDPMethods;

//! \brief  Default USB driver for the current chip
//! \see    S_usb_driver
//! \see    S_usb
extern const S_usb_driver sDefaultDriver;
//! @}

#endif // _USB_H

#define COMM_NUM_ENDPOINTS 3