usb.h

AT91SAM9261的USB设备驱动程序

//! \ingroup usb_api_callbacks
//! \brief Resume callback function
//!
//! Invoked when the device is resumed by the host or attached to the bus. If
//! the suspend callback has put the device into low-power mode, then this
//! function must perform the necessary actions to return it to a normal mode of
//! operation.
//! \see S_usb_suspend
//! \see USB_Attach
//! \see USB_Handler
//! \see S_usb
typedef void (*S_usb_resume)(const S_usb *);

//! \ingroup usb_api_callbacks
//! \brief New Request callback function
//!
//! Invoked when a new SETUP request is received. The request can then be
//! retrieved by using the USB_GetSetup function on the S_usb instance.
//! \see USB_Handler
//! \see S_usb
typedef void (*S_usb_new_request)(const S_usb *);

//! \ingroup usb_api_callbacks
//! \brief  Interrupt SOF callback function
//!
//!         Invoked when a SOF interrupt is received.
//! \see    USB_Handler
//! \see    S_usb
typedef void (*S_usb_int_sof)(const S_usb *);

// Methods
typedef char (*S_usb_write)(const S_usb   *pUsb,
                            unsigned char bEndpoint,
                            const void    *pData,
                            unsigned int  dLength,
                            Callback_f    fCallback,
                            void          *pArgument);
typedef char (*S_usb_read)(const S_usb   *pUsb,
                           unsigned char bEndpoint,
                           void          *pData,
                           unsigned int  dLength,
                           Callback_f    fCallback,
                           void *pArgument);
typedef char (*S_usb_stall)(const S_usb   *pUsb,
                            unsigned char bEndpoint);
typedef bool (*S_usb_halt)(const S_usb   *pUsb,
                           unsigned char bEndpoint,
                           unsigned char bRequest);
typedef void (*S_usb_remote_wakeup)(const S_usb *pUsb);
typedef bool (*S_usb_cfg_endpoint)(const S_usb                     * pUsb,
                                   const S_usb_endpoint_descriptor *pEpDesc);
typedef bool (*S_usb_attach)(const S_usb *);
typedef void (*S_usb_set_address)(const S_usb *);
typedef void (*S_usb_set_cfg)(const S_usb *);
typedef void (*S_usb_handler)(const S_usb *);
typedef void (*S_usb_connect)(const S_usb *);
typedef void (*S_usb_disconnect)(const S_usb *);

//------------------------------------------------------------------------------
//! \ingroup usb_api_struct
//! \brief This structure is used to track the current status of an endpoint,
//!        i.e. the current transfer descriptors, the number of FIFO banks used,
//!        and so forth.
//!
//! Each endpoint used by the firmware must have a corresponding S_usb_endpoint
//! structure associated with it.\n
//! Usage example:
//! \include S_usb_endpoint_example.c
//! \see S_usb_ept_macros
//! \see S_usb
//------------------------------------------------------------------------------
typedef struct {

    // Transfer descriptor
    char                    *pData;             //!< \brief Transfer descriptor
                                                //!< pointer to a buffer where
                                                //!< the data is read/stored
    unsigned int            dBytesRemaining;    //!< \brief Number of remaining
                                                //!< bytes to transfer
    unsigned int            dBytesBuffered;     //!< \brief Number of bytes
                                                //!< which have been buffered
                                                //!< but not yet transferred
    unsigned int            dBytesTransferred;  //!< \brief Number of bytes
                                                //!< transferred for the current
                                                //!< operation
    Callback_f              fCallback;          //!< \brief Callback to invoke
                                                //!< after the current transfer
                                                //!< is complete
    void                    *pArgument;         //!< \brief Argument to pass to
                                                //!< the callback function
    // Hardware information
    unsigned int            wMaxPacketSize;     //!< \brief Maximum packet size
                                                //!< for this endpoint
    unsigned int            dFlag;              //!< \brief Hardware flag to
                                                //!< clear upon data reception
    unsigned char           dNumFIFO;           //!< \brief Number of FIFO
                                                //!< buffers defined for this
                                                //!< endpoint
    volatile unsigned int   dState;             //!< Endpoint internal state

} S_usb_endpoint;

//------------------------------------------------------------------------------
//! \ingroup usb_api_struct
//! \brief Pointers to the low-level methods used by the USB controller.
//!
//! This structure is used to provide an abstraction over which USB controller
//! is used by the chip. This means the USB framework is fully portable between
//! AT91 chips and supports chips with more than one controller.
//! \see UDPMethods
//! \see S_usb_driver
//------------------------------------------------------------------------------
typedef struct {

  S_usb_init            init;
  S_usb_write           write;
  S_usb_read            read;
  S_usb_stall           stall;
  S_usb_halt            halt;
  S_usb_remote_wakeup   remoteWakeUp;
  S_usb_cfg_endpoint    configureEndpoint;
  S_usb_attach          attach;
  S_usb_set_address     setAddress;
  S_usb_set_cfg         setConfiguration;
  S_usb_handler         handler;
  S_usb_connect         connect;
  S_usb_disconnect      disconnect;

} S_driver_methods;

//------------------------------------------------------------------------------
//! \ingroup usb_api_struct
//! \brief Low-level driver structure
//!
//! This structure holds information about the USB controller used, such as
//! a pointer to the physical address of the peripheral, to the endpoints FIFO,
//! etc.\n
//! In most case, it is not necessary to declare a S_usb_driver instance: the
//! defaultDriver global variable can be used. This is not possible for chips
//! which have more than one USB controller in them.\n
//! Usage example:
//! \include S_usb_driver_example.c
//! \see defaultDriver
//! \see S_usb
//------------------------------------------------------------------------------
typedef struct {

    void *                  pInterface;     //!< \brief Pointer to the USB
                                            //!< controller peripheral
    void *                  pEndpointFIFO;  //!< \brief Pointer to the endpoints
                                            //!< FIFO buffers (optional, depends
                                            //!< on the USB controller)
    void *                  pDMAInterface;  //!< \brief Pointer to the USB
                                            //!< controller DMA interface
                                            //!< (optional, depends on the USB
                                            //!< controller)
    unsigned int            dID;            //!< \brief ID of the USB controller
                                            //!< peripheral
    unsigned int            dPMC;           //!< \brief ID to enable the USB
                                            //!< controller peripheral clock
    const S_driver_methods* pMethods;       //!< \brief Pointer to
                                            //!< controller-specific methods
} S_usb_driver;

//------------------------------------------------------------------------------
//! \ingroup usb_api_struct
//! \brief Callbacks used by the USB API to notify the user application of
//!        occuring events
//!
//! Usage example:
//! \include S_usb_callbacks_example.c
//! \see usb_api_callbacks
//! \see S_usb
//------------------------------------------------------------------------------
typedef struct {

    // Callbacks
    S_usb_init          init;           //!< Init callback
    S_usb_reset         reset;          //!< Reset callback
    S_usb_suspend       suspend;        //!< Suspend callback
    S_usb_resume        resume;         //!< Resume callback
    S_usb_new_request   newRequest;     //!< NewRequest callback
    S_usb_int_sof       startOfFrame;   //!< SOF interrupt callback

} S_usb_callbacks;

//------------------------------------------------------------------------------
//! \ingroup usb_api_struct
//! \brief Main USB structure used to store the states of the various
//!        components, such as endpoints, callbacks, and so forth.
//!
//! Usage example:
//! \include S_usb_example.c
//! \see s_usb_dev_state
//! \see s_usb_methods
//------------------------------------------------------------------------------
typedef struct _S_usb {

    const S_usb_driver     *pDriver;        //!< Pointer to the low-level driver
    S_usb_endpoint* const   pEndpoints;     //!< Endpoints list
    unsigned int            dNumEndpoints;  //!< Number of endpoints in list
    const S_usb_callbacks  *pCallbacks;     //!< Pointer to the callbacks
    S_usb_request* const    pSetup;         //!< \brief Pointer to the last
                                            //!< received SETUP packet
    volatile unsigned int* const pState;    //!< Current state of the device
} S_usb;

//------------------------------------------------------------------------------
//      Macros
//------------------------------------------------------------------------------

//------------------------------------------------------------------------------
//! \ingroup usb_api_struct
//! \defgroup s_usb_endpoint_macros S_usb_endpoint - Macros
//! \brief Useful macros when declaring a S_usb_endpoint instance
//! \see S_usb_endpoint
//! @{
//------------------------------------------------------------------------------

//! Declares an endpoint with a single-bank FIFO buffer
#define USB_ENDPOINT_SINGLEBANK {0,0,0,0,0,0,0,0,1,0}

//! Declares an endpoint with a dual-bank FIFO buffer
#define USB_ENDPOINT_DUALBANK {0,0,0,0,0,0,0,0,2,0}
//! @}

//------------------------------------------------------------------------------
//      Inline functions
//------------------------------------------------------------------------------

//------------------------------------------------------------------------------
//! \ingroup  usb_api_struct
//! \defgroup s_usb_methods S_usb - Methods
//! \brief  Methods used to access/modify a S_usb structure
//! \see    S_usb_driver
//! \see    S_usb
//! @{
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
//! \brief  Returns the specified endpoint if it exists or zero if it does not
//! \param  pUsb      Pointer to a S_usb instance
//! \param  bEndpoint Index of endpoint
//! \return Pointer to the requested endpoint, or zero if it does not exist.
//------------------------------------------------------------------------------
extern inline S_usb_endpoint * USB_GetEndpoint(const S_usb   *pUsb,
                                               unsigned char bEndpoint)
{
    if (bEndpoint >= pUsb->dNumEndpoints) {

        return 0;
    }
    else {

        return &pUsb->pEndpoints[bEndpoint];
    }
}

//------------------------------------------------------------------------------
//! \brief  Returns a pointer to the last received SETUP request
//! \param  pUsb Pointer to a S_usb instance
//! \return Pointer to the last received SETUP request
//------------------------------------------------------------------------------
extern inline S_usb_request * USB_GetSetup(const S_usb *pUsb)
{
    return pUsb->pSetup;
}

//------------------------------------------------------------------------------
//! \brief  Returns a pointer to the USB controller peripheral used by a S_usb
//!         instance.
//! \param  pUsb Pointer to a S_usb instance
//! \return Pointer to the USB controller peripheral
//------------------------------------------------------------------------------
extern inline void * USB_GetDriverInterface(const S_usb *pUsb) {

    return pUsb->pDriver->pInterface;
}

//------------------------------------------------------------------------------
//! \brief  Returns the USB controller peripheral ID of a S_usb instance.
//! \param  pUsb Pointer to a S_usb instance
//! \return USB controller peripheral ID
//------------------------------------------------------------------------------
extern inline unsigned int USB_GetDriverID(const S_usb *pUsb) {

    return pUsb->pDriver->dID;
}

//------------------------------------------------------------------------------
//! \brief  Returns the USB controller peripheral ID used to enable the
//!         peripheral clock
//! \param  pUsb Pointer to a S_usb instance
//! \return USB controller peripheral ID to enable the peripheral clock
//------------------------------------------------------------------------------
extern inline unsigned int USB_GetDriverPMC(const S_usb *pUsb) {

    return pUsb->pDriver->dPMC;
}

//! @}

//------------------------------------------------------------------------------
//      Callbacks
//------------------------------------------------------------------------------
// Invokes the init callback if it exists
static inline void USB_InitCallback(const S_usb *pUsb)
{
    if (pUsb->pCallbacks->init != 0) {

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

// Invokes the reset callback if it exists
static inline void USB_ResetCallback(const S_usb *pUsb)
{
    if (pUsb->pCallbacks->reset != 0) {

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

// Invokes the suspend callback if it exists
static inline void USB_SuspendCallback(const S_usb *pUsb)
{
    if (pUsb->pCallbacks->suspend != 0) {

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

// Invokes the resume callback if it exists
static inline void USB_ResumeCallback(const S_usb *pUsb)
{
    if (pUsb->pCallbacks->resume != 0) {

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

// Invokes the new request callback if it exists