Group USBD_CORE

Modules > USBD_CORE

Contains core API.

Classes

Type	Name
struct	_usbd_device Represents a USB device data.
struct	usbd_ctlreq Represents generic USB control request.
struct	usbd_status

Public Types

Type	Name
enum	_usbd_respond Reporting status results.
typedef usbd_respond(*	usbd_cfg_callback USB set configuration callback function.
typedef usbd_respond(*	usbd_ctl_callback USB control callback function.
enum	usbd_ctl_state USB device control endpoint machine state.
typedef struct _usbd_device	usbd_device
typedef usbd_respond(*	usbd_dsc_callback USB get descriptor callback function.
typedef void(*	usbd_evt_callback Generic USB device event callback for events and endpoints processing.
enum	usbd_machine_state USB device machine states.
typedef enum _usbd_respond	usbd_respond Reporting status results.
typedef void(*	usbd_rqc_callback USB control transfer completed callback function.

Public Functions

Type	Name
void	usbd_poll (usbd_device * dev) Polls USB for events.

Public Static Functions

Type	Name
uint8_t	usbd_connect (usbd_device * dev, bool connect) Connects or disconnects USB hardware to/from usb host.
void	usbd_enable (usbd_device * dev, bool enable) Enables or disables USB hardware.
bool	usbd_ep_config (usbd_device * dev, uint8_t ep, uint8_t eptype, uint16_t epsize) Configure endpoint.
void	usbd_ep_deconfig (usbd_device * dev, uint8_t ep) Deconfigure endpoint.
int32_t	usbd_ep_read (usbd_device * dev, uint8_t ep, void * buf, uint16_t blen) Read data from endpoint.
void	usbd_ep_stall (usbd_device * dev, uint8_t ep) Stall endpoint.
void	usbd_ep_unstall (usbd_device * dev, uint8_t ep) Unstall endpoint.
int32_t	usbd_ep_write (usbd_device * dev, uint8_t ep, void * buf, uint16_t blen) Write data to endpoint.
uint32_t	usbd_getinfo (usbd_device * dev) Retrieves status and capabilities.
void	usbd_init (usbd_device * dev, const struct usbd_driver * drv, const uint8_t ep0size, uint32_t * buffer, const uint16_t bsize) Initializes device structure.
void	usbd_reg_config (usbd_device * dev, usbd_cfg_callback callback) Register callback for SET_CONFIG control request.
void	usbd_reg_control (usbd_device * dev, usbd_ctl_callback callback) Register callback for all control requests.
void	usbd_reg_descr (usbd_device * dev, usbd_dsc_callback callback) Register callback for GET_DESCRIPTOR control request.
void	usbd_reg_endpoint (usbd_device * dev, uint8_t ep, usbd_evt_callback callback) Register endpoint callback.
void	usbd_reg_event (usbd_device * dev, uint8_t evt, usbd_evt_callback callback) Registers event callback.

Macros

Type	Name
define	USB_EPTYPE_DBLBUF 0x04 Doublebuffered endpoint (bulk endpoint only).
define	USB_REQ_CLASS (1 << 5) Class specified request.
define	USB_REQ_DEVICE (0 << 0) Request to device.
define	USB_REQ_DEVTOHOST (1 << 7) Request direction is DEVICE to HOST.
define	USB_REQ_DIRECTION (1 << 7) Request direction mask.
define	USB_REQ_ENDPOINT (2 << 0) Request to endpoint.
define	USB_REQ_HOSTTODEV (0 << 7) Request direction is HOST to DEVICE.
define	USB_REQ_INTERFACE (1 << 0) Request to interface.
define	USB_REQ_OTHER (3 << 0) Other request.
define	USB_REQ_RECIPIENT (3 << 0) Request recipient mask.
define	USB_REQ_STANDARD (0 << 5) Standard request.
define	USB_REQ_TYPE (3 << 5) Request type mask.
define	USB_REQ_VENDOR (2 << 5) Vendor specified request.

Public Types Documentation

enum _usbd_respond

enum _usbd_respond {
    usbd_fail,
    usbd_ack,
    usbd_nak
};

typedef usbd_cfg_callback

USB set configuration callback function.

typedef usbd_respond(* usbd_cfg_callback) (usbd_device *dev, uint8_t cfg);

called when SET_CONFIGURATION request issued

Parameters:

• dev pointer to USB device
• cfg configuration number.

Note:

if config is 0 device endpoints should be de-configured

Returns:

TRUE if success

typedef usbd_ctl_callback

USB control callback function.

typedef usbd_respond(* usbd_ctl_callback) (usbd_device *dev, usbd_ctlreq *req, usbd_rqc_callback *callback);

Uses for the control request processing. Some requests will be handled by core if callback don't process it (returns FALSE). If request was not processed STALL PID will be issued. * GET_CONFIGURATION * SET_CONFIGURATION (passes to usbd_cfg_callback) * GET_DESCRIPTOR (passes to usbd_dsc_callback) * GET_STATUS * SET_FEATURE, CLEAR_FEATURE (endpoints only) * SET_ADDRESS

Parameters:

• dev points to USB device
• req points to usb control request
• *callback USB control transfer completion callback, default is NULL (no callback)

Returns:

usbd_respond status.

enum usbd_ctl_state

enum usbd_ctl_state {
    usbd_ctl_idle,
    usbd_ctl_rxdata,
    usbd_ctl_txdata,
    usbd_ctl_ztxdata,
    usbd_ctl_lastdata,
    usbd_ctl_statusin,
    usbd_ctl_statusout
};

typedef usbd_device

typedef struct _usbd_device usbd_device;

typedef usbd_dsc_callback

USB get descriptor callback function.

typedef usbd_respond(* usbd_dsc_callback) (usbd_ctlreq *req, void **address, uint16_t *dsize);

Called when GET_DESCRIPTOR request issued

Parameters:

• req pointer to usb control request structure
• address pointer to the descriptor in memory. Points to req->data by default. You can use this buffer.
• dsize descriptor size. maximum buffer size by default.

Returns:

usbd_ack if you passed the correct descriptor, usbd_fail otherwise.

typedef usbd_evt_callback

Generic USB device event callback for events and endpoints processing.

typedef void(* usbd_evt_callback) (usbd_device *dev, uint8_t event, uint8_t ep);

Parameters:

• dev pointer to USB device
• event USB event
• ep active endpoint number

Note:

endpoints with same indexes i.e. 0x01 and 0x81 shares same callback.

enum usbd_machine_state

enum usbd_machine_state {
    usbd_state_disabled,
    usbd_state_disconnected,
    usbd_state_default,
    usbd_state_addressed,
    usbd_state_configured
};

typedef usbd_respond

typedef enum _usbd_respond usbd_respond;

typedef usbd_rqc_callback

USB control transfer completed callback function.

typedef void(* usbd_rqc_callback) (usbd_device *dev, usbd_ctlreq *req);

Parameters:

• dev pointer to USB device
• req pointer to usb request structure

Note:

usbd_device->complete_callback will be set to NULL after this callback completion.

Public Functions Documentation

function usbd_poll

Polls USB for events.

void usbd_poll (
    usbd_device * dev
) 

Parameters:

• dev Pointer to device structure

Note:

can be called as from main routine as from USB interrupt

Public Static Functions Documentation

function usbd_connect

Connects or disconnects USB hardware to/from usb host.

static inline uint8_t usbd_connect (
    usbd_device * dev,
    bool connect
) 

Parameters:

• dev dev usb device _usbd_device
• connect Connects USB to host if TRUE, disconnects otherwise

Returns:

lanes connection status. USB_LANES_STATUS

function usbd_enable

Enables or disables USB hardware.

static inline void usbd_enable (
    usbd_device * dev,
    bool enable
) 

Parameters:

• dev dev usb device _usbd_device
• enable Enables USB when TRUE disables otherwise

function usbd_ep_config

Configure endpoint.

static inline bool usbd_ep_config (
    usbd_device * dev,
    uint8_t ep,
    uint8_t eptype,
    uint16_t epsize
) 

Parameters:

• dev dev usb device _usbd_device
• ep endpoint address. Use USB_EPDIR_ macros to set endpoint direction
• eptype endpoint type. Use USB_EPTYPE_* macros.
• epsize endpoint size in bytes

Returns:

TRUE if success

function usbd_ep_deconfig

Deconfigure endpoint.

static inline void usbd_ep_deconfig (
    usbd_device * dev,
    uint8_t ep
) 

Parameters:

• dev dev usb device _usbd_device
• ep endpoint index

Note:

if you have two one-direction single-buffered endpoints with same index (i.e. 0x02 and 0x82) both will be deconfigured.

function usbd_ep_read

Read data from endpoint.

static inline int32_t usbd_ep_read (
    usbd_device * dev,
    uint8_t ep,
    void * buf,
    uint16_t blen
) 

Parameters:

• dev dev usb device _usbd_device
• ep endpoint index, should belong to OUT or CONTROL endpoint.
• buf pointer to read buffer
• blen size of the read buffer in bytes

Returns:

size of the actually received data, -1 on error.

function usbd_ep_stall

Stall endpoint.

static inline void usbd_ep_stall (
    usbd_device * dev,
    uint8_t ep
) 

Parameters:

• dev dev usb device _usbd_device
• ep endpoint address

function usbd_ep_unstall

Unstall endpoint.

static inline void usbd_ep_unstall (
    usbd_device * dev,
    uint8_t ep
) 

Parameters:

• dev dev usb device _usbd_device
• ep endpoint address

function usbd_ep_write

Write data to endpoint.

static inline int32_t usbd_ep_write (
    usbd_device * dev,
    uint8_t ep,
    void * buf,
    uint16_t blen
) 

Parameters:

• dev dev usb device _usbd_device
• ep endpoint index, hould belong to IN or CONTROL endpoint
• buf pointer to data buffer
• blen size of data will be written

Returns:

number of written bytes

function usbd_getinfo

Retrieves status and capabilities.

static inline uint32_t usbd_getinfo (
    usbd_device * dev
) 

Returns:

current HW status, enumeration speed and capabilities USBD_HW_CAPS

function usbd_init

Initializes device structure.

static inline void usbd_init (
    usbd_device * dev,
    const struct usbd_driver * drv,
    const uint8_t ep0size,
    uint32_t * buffer,
    const uint16_t bsize
) 

Parameters:

• dev USB device that will be initialized
• drv Pointer to hardware driver
• ep0size Control endpoint 0 size
• buffer Pointer to control request data buffer (32-bit aligned)
• bsize Size of the data buffer

function usbd_reg_config

Register callback for SET_CONFIG control request.

static inline void usbd_reg_config (
    usbd_device * dev,
    usbd_cfg_callback callback
) 

Parameters:

• dev dev usb device _usbd_device
• callback pointer to user usbd_cfg_callback

function usbd_reg_control

Register callback for all control requests.

static inline void usbd_reg_control (
    usbd_device * dev,
    usbd_ctl_callback callback
) 

Parameters:

• dev usb device _usbd_device
• callback user control callback usbd_ctl_callback

function usbd_reg_descr

Register callback for GET_DESCRIPTOR control request.

static inline void usbd_reg_descr (
    usbd_device * dev,
    usbd_dsc_callback callback
) 

Parameters:

• dev dev usb device _usbd_device
• callback pointer to user usbd_ctl_callback

function usbd_reg_endpoint

Register endpoint callback.

static inline void usbd_reg_endpoint (
    usbd_device * dev,
    uint8_t ep,
    usbd_evt_callback callback
) 

Parameters:

• dev dev usb device _usbd_device
• ep endpoint index
• callback pointer to user usbd_evt_callback callback for endpoint events

function usbd_reg_event

Registers event callback.

static inline void usbd_reg_event (
    usbd_device * dev,
    uint8_t evt,
    usbd_evt_callback callback
) 

Parameters:

• dev dev usb device _usbd_device
• evt device event wants to be registered
• callback pointer to user usbd_evt_callback for this event

Macro Definition Documentation

define USB_EPTYPE_DBLBUF

#define USB_EPTYPE_DBLBUF 0x04

define USB_REQ_CLASS

#define USB_REQ_CLASS (1 << 5)

define USB_REQ_DEVICE

#define USB_REQ_DEVICE (0 << 0)

define USB_REQ_DEVTOHOST

#define USB_REQ_DEVTOHOST (1 << 7)

define USB_REQ_DIRECTION

#define USB_REQ_DIRECTION (1 << 7)

define USB_REQ_ENDPOINT

#define USB_REQ_ENDPOINT (2 << 0)

define USB_REQ_HOSTTODEV

#define USB_REQ_HOSTTODEV (0 << 7)

define USB_REQ_INTERFACE

#define USB_REQ_INTERFACE (1 << 0)

define USB_REQ_OTHER

#define USB_REQ_OTHER (3 << 0)

define USB_REQ_RECIPIENT

#define USB_REQ_RECIPIENT (3 << 0)

define USB_REQ_STANDARD

#define USB_REQ_STANDARD (0 << 5)

define USB_REQ_TYPE

#define USB_REQ_TYPE (3 << 5)

define USB_REQ_VENDOR

#define USB_REQ_VENDOR (2 << 5)

---