libopencm3
A free/libre/open-source firmware library for various ARM Cortex-M3 microcontrollers.
USB Drivers

Defined Constants and Types for the USB Drivers More...

Macros

#define otgfs_usb_driver   stm32f107_usb_driver
 
#define otghs_usb_driver   stm32f207_usb_driver
 

Typedefs

typedef struct _usbd_driver usbd_driver
 
typedef struct _usbd_device usbd_device
 
typedef void(* usbd_control_complete_callback) (usbd_device *usbd_dev, struct usb_setup_data *req)
 
typedef enum usbd_request_return_codes(* usbd_control_callback) (usbd_device *usbd_dev, struct usb_setup_data *req, uint8_t **buf, uint16_t *len, usbd_control_complete_callback *complete)
 
typedef void(* usbd_set_config_callback) (usbd_device *usbd_dev, uint16_t wValue)
 
typedef void(* usbd_set_altsetting_callback) (usbd_device *usbd_dev, uint16_t wIndex, uint16_t wValue)
 
typedef void(* usbd_endpoint_callback) (usbd_device *usbd_dev, uint8_t ep)
 

Enumerations

enum  usbd_request_return_codes { USBD_REQ_NOTSUPP = 0 , USBD_REQ_HANDLED = 1 , USBD_REQ_NEXT_CALLBACK = 2 }
 

Functions

usbd_deviceusbd_init (const usbd_driver *driver, const struct usb_device_descriptor *dev, const struct usb_config_descriptor *conf, const char *const *strings, int num_strings, uint8_t *control_buffer, uint16_t control_buffer_size)
 Main initialization entry point. More...
 
void usbd_register_reset_callback (usbd_device *usbd_dev, void(*callback)(void))
 Registers a reset callback. More...
 
void usbd_register_suspend_callback (usbd_device *usbd_dev, void(*callback)(void))
 Registers a suspend callback. More...
 
void usbd_register_resume_callback (usbd_device *usbd_dev, void(*callback)(void))
 Registers a resume callback. More...
 
void usbd_register_sof_callback (usbd_device *usbd_dev, void(*callback)(void))
 Registers a SOF callback. More...
 
int usbd_register_control_callback (usbd_device *usbd_dev, uint8_t type, uint8_t type_mask, usbd_control_callback callback)
 Registers a control callback. More...
 
int usbd_register_set_config_callback (usbd_device *usbd_dev, usbd_set_config_callback callback)
 Registers a "Set Config" callback. More...
 
void usbd_register_set_altsetting_callback (usbd_device *usbd_dev, usbd_set_altsetting_callback callback)
 Registers a "Set Interface" (alternate setting) callback. More...
 
void usbd_register_extra_string (usbd_device *usbd_dev, int index, const char *string)
 Registers a non-contiguous string descriptor. More...
 
void usbd_poll (usbd_device *usbd_dev)
 
void usbd_disconnect (usbd_device *usbd_dev, bool disconnected)
 Disconnect, if supported by the driver. More...
 
void usbd_ep_setup (usbd_device *usbd_dev, uint8_t addr, uint8_t type, uint16_t max_size, usbd_endpoint_callback callback)
 Setup an endpoint. More...
 
uint16_t usbd_ep_write_packet (usbd_device *usbd_dev, uint8_t addr, const void *buf, uint16_t len)
 Write a packet. More...
 
uint16_t usbd_ep_read_packet (usbd_device *usbd_dev, uint8_t addr, void *buf, uint16_t len)
 Read a packet. More...
 
void usbd_ep_stall_set (usbd_device *usbd_dev, uint8_t addr, uint8_t stall)
 Set/clear STALL condition on an endpoint. More...
 
uint8_t usbd_ep_stall_get (usbd_device *usbd_dev, uint8_t addr)
 Get STALL status of an endpoint. More...
 
void usbd_ep_nak_set (usbd_device *usbd_dev, uint8_t addr, uint8_t nak)
 Set an Out endpoint to NAK. More...
 

Variables

const usbd_driver st_usbfs_v1_usb_driver
 
const usbd_driver stm32f107_usb_driver
 
const usbd_driver stm32f207_usb_driver
 
const usbd_driver st_usbfs_v2_usb_driver
 
const usbd_driver efm32lg_usb_driver
 
const usbd_driver efm32hg_usb_driver
 
const usbd_driver lm4f_usb_driver
 

Detailed Description

Defined Constants and Types for the USB Drivers

Version
1.0.0
Author
© 2010 Gareth McMullin garet.nosp@m.h@bl.nosp@m.acksp.nosp@m.here.nosp@m..co.n.nosp@m.z
Date
10 March 2013

LGPL License Terms libopencm3 License

Macro Definition Documentation

◆ otgfs_usb_driver

#define otgfs_usb_driver   stm32f107_usb_driver

Definition at line 59 of file usbd.h.

◆ otghs_usb_driver

#define otghs_usb_driver   stm32f207_usb_driver

Definition at line 60 of file usbd.h.

Typedef Documentation

◆ usbd_control_callback

typedef enum usbd_request_return_codes(* usbd_control_callback) (usbd_device *usbd_dev, struct usb_setup_data *req, uint8_t **buf, uint16_t *len, usbd_control_complete_callback *complete)

Definition at line 117 of file usbd.h.

◆ usbd_control_complete_callback

typedef void(* usbd_control_complete_callback) (usbd_device *usbd_dev, struct usb_setup_data *req)

Definition at line 117 of file usbd.h.

◆ usbd_device

typedef struct _usbd_device usbd_device

Definition at line 53 of file usbd.h.

◆ usbd_driver

typedef struct _usbd_driver usbd_driver

Definition at line 52 of file usbd.h.

◆ usbd_endpoint_callback

typedef void(* usbd_endpoint_callback) (usbd_device *usbd_dev, uint8_t ep)

Definition at line 131 of file usbd.h.

◆ usbd_set_altsetting_callback

typedef void(* usbd_set_altsetting_callback) (usbd_device *usbd_dev, uint16_t wIndex, uint16_t wValue)

Definition at line 128 of file usbd.h.

◆ usbd_set_config_callback

typedef void(* usbd_set_config_callback) (usbd_device *usbd_dev, uint16_t wValue)

Definition at line 125 of file usbd.h.

Enumeration Type Documentation

◆ usbd_request_return_codes

Enumerator
USBD_REQ_NOTSUPP 
USBD_REQ_HANDLED 
USBD_REQ_NEXT_CALLBACK 

Definition at line 46 of file usbd.h.

Function Documentation

◆ usbd_disconnect()

void usbd_disconnect ( usbd_device usbd_dev,
bool  disconnected 
)

Disconnect, if supported by the driver.

This function is implemented as weak function and can be replaced by an application specific version to handle chips that don't have built-in handling for this (e.g. STM32F1.)

Parameters
usbd_devthe usb device handle returned from usbd_init
disconnectedtrue to request a disconnect

Definition at line 131 of file usb.c.

References usbd_dev.

◆ usbd_ep_nak_set()

void usbd_ep_nak_set ( usbd_device usbd_dev,
uint8_t  addr,
uint8_t  nak 
)

Set an Out endpoint to NAK.

Parameters
usbd_devthe usb device handle returned from usbd_init
addrEP address
nakif nonzero, set NAK

Definition at line 168 of file usb.c.

References usbd_dev.

Referenced by _usbd_control_in(), _usbd_control_setup(), and usb_control_setup_write().

Here is the caller graph for this function:

◆ usbd_ep_read_packet()

uint16_t usbd_ep_read_packet ( usbd_device usbd_dev,
uint8_t  addr,
void *  buf,
uint16_t  len 
)

Read a packet.

Parameters
usbd_devthe usb device handle returned from usbd_init
addrEP address
bufuser buffer that will receive data
len# of bytes
Returns
Actual # of bytes read

Definition at line 152 of file usb.c.

References usbd_dev.

Referenced by _usbd_control_out(), msc_data_rx_cb(), and usb_control_recv_chunk().

Here is the caller graph for this function:

◆ usbd_ep_setup()

void usbd_ep_setup ( usbd_device usbd_dev,
uint8_t  addr,
uint8_t  type,
uint16_t  max_size,
usbd_endpoint_callback  callback 
)

Setup an endpoint.

Parameters
usbd_devthe usb device handle returned from usbd_init
addrFull EP address including direction (e.g. 0x01 or 0x81)
typeValue for bmAttributes (USB_ENDPOINT_ATTR_*)
max_sizeEndpoint max size
callbackyour desired callback function
Note
The stack only supports 8 endpoints, 0..7, so don't try and use arbitrary addresses here, even though USB itself would allow this. Not all backends support arbitrary addressing anyway.

Definition at line 140 of file usb.c.

References usbd_dev.

Referenced by _usbd_reset(), and msc_set_config().

Here is the caller graph for this function:

◆ usbd_ep_stall_get()

uint8_t usbd_ep_stall_get ( usbd_device usbd_dev,
uint8_t  addr 
)

Get STALL status of an endpoint.

Parameters
usbd_devthe usb device handle returned from usbd_init
addrFull EP address (with direction bit)
Returns
nonzero if endpoint is stalled

Definition at line 163 of file usb.c.

References usbd_dev.

Referenced by usb_standard_endpoint_get_status().

Here is the caller graph for this function:

◆ usbd_ep_stall_set()

void usbd_ep_stall_set ( usbd_device usbd_dev,
uint8_t  addr,
uint8_t  stall 
)

Set/clear STALL condition on an endpoint.

Parameters
usbd_devthe usb device handle returned from usbd_init
addrFull EP address (with direction bit)
stallif 0, clear STALL, else set stall.

Definition at line 158 of file usb.c.

References usbd_dev.

Referenced by stall_transaction(), usb_standard_endpoint_stall(), and usb_standard_endpoint_unstall().

Here is the caller graph for this function:

◆ usbd_ep_write_packet()

uint16_t usbd_ep_write_packet ( usbd_device usbd_dev,
uint8_t  addr,
const void *  buf,
uint16_t  len 
)

Write a packet.

Parameters
usbd_devthe usb device handle returned from usbd_init
addrEP address (direction is ignored)
bufpointer to user data to write
len# of bytes
Returns
0 if failed, len if successful

Definition at line 146 of file usb.c.

References usbd_dev.

Referenced by _usbd_control_out(), msc_data_rx_cb(), msc_data_tx_cb(), usb_control_send_chunk(), and usb_control_setup_read().

Here is the caller graph for this function:

◆ usbd_init()

usbd_device * usbd_init ( const usbd_driver driver,
const struct usb_device_descriptor dev,
const struct usb_config_descriptor conf,
const char *const *  strings,
int  num_strings,
uint8_t *  control_buffer,
uint16_t  control_buffer_size 
)

Main initialization entry point.

Initialize the USB firmware library to implement the USB device described by the descriptors provided.

It is required that the 48MHz USB clock is already available.

Parameters
driverTODO
devPointer to USB device descriptor. This must not be changed while the device is in use.
confPointer to array of USB configuration descriptors. These must not be changed while the device is in use. The length of this array is determined by the bNumConfigurations field in the device descriptor.
stringsPointer to an array of strings for USB string descriptors. Referenced in iSomething fields, e.g. iManufacturer. Since a zero index means "no string", an iSomething value of 1 refers strings[0].
num_stringsNumber of items in strings array.
control_bufferPointer to array that would hold the data received during control requests with DATA stage
control_buffer_sizeSize of control_buffer
Returns
the usb device initialized for use. (currently cannot fail).

To place strings entirely into Flash/read-only memory, use

static const * const strings[] = { ... };

(note the double const.) The first const refers to the strings while the second const refers to the array.

Definition at line 42 of file usb.c.

References _usbd_control_in(), _usbd_control_out(), _usbd_control_setup(), and usbd_dev.

Here is the call graph for this function:

◆ usbd_poll()

void usbd_poll ( usbd_device usbd_dev)

Definition at line 126 of file usb.c.

References usbd_dev.

◆ usbd_register_control_callback()

int usbd_register_control_callback ( usbd_device usbd_dev,
uint8_t  type,
uint8_t  type_mask,
usbd_control_callback  callback 
)

Registers a control callback.

Since the list of user control callbacks is cleared every time device configuration is set (inside usb_standard_set_configuration()), control callback registration must happen inside (or after) the config callback. The specified callback will be called if (type == (bmRequestType & type_mask)).

See also
usbd_register_set_config_callback
Parameters
usbd_devthe usb device handle returned from usbd_init
typeHandled request type
type_maskMask to apply before matching request type
callbackyour desired callback function
Returns
0 if successful

Definition at line 73 of file usb_control.c.

References usbd_dev.

Referenced by msc_set_config().

Here is the caller graph for this function:

◆ usbd_register_extra_string()

void usbd_register_extra_string ( usbd_device usbd_dev,
int  index,
const char *  string 
)

Registers a non-contiguous string descriptor.

Definition at line 99 of file usb.c.

References usbd_dev.

◆ usbd_register_reset_callback()

void usbd_register_reset_callback ( usbd_device usbd_dev,
void(*)(void)  callback 
)

Registers a reset callback.

Definition at line 77 of file usb.c.

References usbd_dev.

◆ usbd_register_resume_callback()

void usbd_register_resume_callback ( usbd_device usbd_dev,
void(*)(void)  callback 
)

Registers a resume callback.

Definition at line 88 of file usb.c.

References usbd_dev.

◆ usbd_register_set_altsetting_callback()

void usbd_register_set_altsetting_callback ( usbd_device usbd_dev,
usbd_set_altsetting_callback  callback 
)

Registers a "Set Interface" (alternate setting) callback.

Parameters
usbd_devthe usb device handle returned from usbd_init
callbackyour desired callback function

Definition at line 62 of file usb_standard.c.

References usbd_dev.

◆ usbd_register_set_config_callback()

int usbd_register_set_config_callback ( usbd_device usbd_dev,
usbd_set_config_callback  callback 
)

Registers a "Set Config" callback.

Parameters
usbd_devthe usb device handle returned from usbd_init
callbackyour desired callback function
Returns
0 if successful or already existed.
-1 if no more space was available for callbacks.

Definition at line 42 of file usb_standard.c.

References usbd_dev.

Referenced by usb_msc_init().

Here is the caller graph for this function:

◆ usbd_register_sof_callback()

void usbd_register_sof_callback ( usbd_device usbd_dev,
void(*)(void)  callback 
)

Registers a SOF callback.

Definition at line 94 of file usb.c.

References usbd_dev.

◆ usbd_register_suspend_callback()

void usbd_register_suspend_callback ( usbd_device usbd_dev,
void(*)(void)  callback 
)

Registers a suspend callback.

Definition at line 82 of file usb.c.

References usbd_dev.

Variable Documentation

◆ efm32hg_usb_driver

const usbd_driver efm32hg_usb_driver
extern

◆ efm32lg_usb_driver

const usbd_driver efm32lg_usb_driver
extern

◆ lm4f_usb_driver

const usbd_driver lm4f_usb_driver
extern

◆ st_usbfs_v1_usb_driver

const usbd_driver st_usbfs_v1_usb_driver
extern

◆ st_usbfs_v2_usb_driver

const usbd_driver st_usbfs_v2_usb_driver
extern

◆ stm32f107_usb_driver

const usbd_driver stm32f107_usb_driver
extern

Definition at line 36 of file usb_f107.c.

Referenced by stm32f107_usbd_init().

◆ stm32f207_usb_driver

const usbd_driver stm32f207_usb_driver
extern

Definition at line 36 of file usb_f207.c.

Referenced by stm32f207_usbd_init().