2013-03-10 23:06:57 +00:00
|
|
|
/** @defgroup usb_driver_defines USB Drivers
|
|
|
|
|
|
|
|
@brief <b>Defined Constants and Types for the USB Drivers</b>
|
|
|
|
|
|
|
|
@ingroup USB_defines
|
|
|
|
|
|
|
|
@version 1.0.0
|
|
|
|
|
2013-06-13 00:44:07 +00:00
|
|
|
@author @htmlonly © @endhtmlonly 2010
|
|
|
|
Gareth McMullin <gareth@blacksphere.co.nz>
|
2013-03-10 23:06:57 +00:00
|
|
|
|
|
|
|
@date 10 March 2013
|
|
|
|
|
|
|
|
LGPL License Terms @ref lgpl_license
|
|
|
|
*/
|
|
|
|
|
2010-11-02 01:02:21 +00:00
|
|
|
/*
|
2010-12-30 12:19:25 +00:00
|
|
|
* This file is part of the libopencm3 project.
|
2010-11-02 01:02:21 +00:00
|
|
|
*
|
2010-12-29 15:43:26 +00:00
|
|
|
* Copyright (C) 2010 Gareth McMullin <gareth@blacksphere.co.nz>
|
2010-11-02 01:02:21 +00:00
|
|
|
*
|
2012-03-02 10:23:11 +00:00
|
|
|
* This library is free software: you can redistribute it and/or modify
|
|
|
|
* it under the terms of the GNU Lesser General Public License as published by
|
2010-11-02 01:02:21 +00:00
|
|
|
* the Free Software Foundation, either version 3 of the License, or
|
|
|
|
* (at your option) any later version.
|
|
|
|
*
|
2012-03-02 10:23:11 +00:00
|
|
|
* This library is distributed in the hope that it will be useful,
|
2010-11-02 01:02:21 +00:00
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
2012-03-02 10:23:11 +00:00
|
|
|
* GNU Lesser General Public License for more details.
|
2010-11-02 01:02:21 +00:00
|
|
|
*
|
2012-03-02 10:23:11 +00:00
|
|
|
* You should have received a copy of the GNU Lesser General Public License
|
|
|
|
* along with this library. If not, see <http://www.gnu.org/licenses/>.
|
2010-11-02 01:02:21 +00:00
|
|
|
*/
|
2010-12-29 15:43:26 +00:00
|
|
|
|
2013-03-10 23:06:57 +00:00
|
|
|
/**@{*/
|
|
|
|
|
2010-11-02 01:02:21 +00:00
|
|
|
#ifndef __USBD_H
|
|
|
|
#define __USBD_H
|
|
|
|
|
2010-12-31 17:18:39 +00:00
|
|
|
#include <libopencm3/usb/usbstd.h>
|
2010-11-02 01:02:21 +00:00
|
|
|
|
2012-09-02 15:12:58 +00:00
|
|
|
BEGIN_DECLS
|
|
|
|
|
2012-11-07 18:33:51 +00:00
|
|
|
|
|
|
|
enum usbd_request_return_codes {
|
|
|
|
USBD_REQ_NOTSUPP = 0,
|
|
|
|
USBD_REQ_HANDLED = 1,
|
|
|
|
USBD_REQ_NEXT_CALLBACK = 2,
|
|
|
|
};
|
|
|
|
|
2011-01-30 04:04:56 +00:00
|
|
|
typedef struct _usbd_driver usbd_driver;
|
2012-08-17 01:50:38 +00:00
|
|
|
typedef struct _usbd_device usbd_device;
|
|
|
|
|
usb: extract ST USB FS peripheral core. [BREAKING CHANGE]
The breaking changes here changes in header location, and changes in driver
name passed down to the usb stack.
Changes affect: stm32f102/f103, stm32l1, and some f3 parts
* instead of the confusingly generic "usb" use the name "st_usbfs" for the USB
Full speed peripheral ST provides in a variety of their stm32 products.
Include directives should change as:
#include <libopencm3/stm32/usb.h> => <libopencm3/stm32/st_usbfs.h>
* instead of the confusingly specific "f103" name for the driver, use
"st_usbfs_v1" [BREAKING_CHANGE]
Instead of:
usbd_init(&stm32f103_usb_driver, .....) ==>
usbd_init(&st_usbfs_v1_usb_driver, .....) ==>
The purpose of these changes is to reduce some confusion around naming, but
primarily to prepare for the "v2" peripheral available on stm32f0/l0 and some
f3 devices.
Work by Frantisek Burian, Kuldeep Singh Dhaka, Robin Kreis, fenugrec and zyp
on irc, and all those forgotten.
2015-10-02 00:41:25 +00:00
|
|
|
extern const usbd_driver st_usbfs_v1_usb_driver;
|
2011-02-10 06:58:51 +00:00
|
|
|
extern const usbd_driver stm32f107_usb_driver;
|
2012-08-17 01:50:38 +00:00
|
|
|
extern const usbd_driver stm32f207_usb_driver;
|
2015-10-02 01:30:25 +00:00
|
|
|
extern const usbd_driver st_usbfs_v2_usb_driver;
|
2011-12-17 01:11:39 +00:00
|
|
|
#define otgfs_usb_driver stm32f107_usb_driver
|
2012-08-17 01:50:38 +00:00
|
|
|
#define otghs_usb_driver stm32f207_usb_driver
|
2015-03-25 00:00:10 +00:00
|
|
|
extern const usbd_driver efm32lg_usb_driver;
|
2018-02-19 00:23:27 +00:00
|
|
|
extern const usbd_driver efm32hg_usb_driver;
|
2018-08-27 15:00:06 +00:00
|
|
|
extern const usbd_driver lm4f_usb_driver;
|
2011-01-30 04:04:56 +00:00
|
|
|
|
2010-11-02 01:02:21 +00:00
|
|
|
/* <usb.c> */
|
2015-10-13 18:22:33 +00:00
|
|
|
/**
|
|
|
|
* 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.
|
|
|
|
*
|
|
|
|
* @param driver TODO
|
|
|
|
* @param dev Pointer to USB device descriptor. This must not be changed while
|
|
|
|
* the device is in use.
|
|
|
|
* @param conf Pointer 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.
|
2018-03-31 00:54:00 +00:00
|
|
|
* @param strings Pointer to an array of strings for USB string descriptors.
|
|
|
|
* Referenced in @e iSomething fields, e.g. @a iManufacturer.
|
|
|
|
* Since a zero index means "no string", an iSomething value of
|
|
|
|
* 1 refers strings[0].
|
|
|
|
* @param num_strings Number of items in @a strings array.
|
2015-10-13 18:22:33 +00:00
|
|
|
* @param control_buffer Pointer to array that would hold the data
|
|
|
|
* received during control requests with DATA
|
|
|
|
* stage
|
|
|
|
* @param control_buffer_size Size of control_buffer
|
|
|
|
* @return the usb device initialized for use. (currently cannot fail).
|
2018-03-31 00:54:00 +00:00
|
|
|
*
|
|
|
|
* To place @a strings entirely into Flash/read-only memory, use
|
|
|
|
* @code static const * const strings[] = { ... }; @endcode
|
|
|
|
* (note the double @e const.) The first @e const refers to the strings
|
|
|
|
* while the second @e const refers to the array.
|
2015-10-13 18:22:33 +00:00
|
|
|
*/
|
2013-06-13 00:44:07 +00:00
|
|
|
extern usbd_device * usbd_init(const usbd_driver *driver,
|
|
|
|
const struct usb_device_descriptor *dev,
|
|
|
|
const struct usb_config_descriptor *conf,
|
2018-03-31 00:54:00 +00:00
|
|
|
const char * const *strings, int num_strings,
|
2013-06-13 04:00:50 +00:00
|
|
|
uint8_t *control_buffer,
|
|
|
|
uint16_t control_buffer_size);
|
2012-08-17 01:50:38 +00:00
|
|
|
|
2015-10-13 18:22:33 +00:00
|
|
|
/** Registers a reset callback */
|
2012-08-17 01:50:38 +00:00
|
|
|
extern void usbd_register_reset_callback(usbd_device *usbd_dev,
|
|
|
|
void (*callback)(void));
|
2015-10-13 18:22:33 +00:00
|
|
|
/** Registers a suspend callback */
|
2012-08-17 01:50:38 +00:00
|
|
|
extern void usbd_register_suspend_callback(usbd_device *usbd_dev,
|
|
|
|
void (*callback)(void));
|
2015-10-13 18:22:33 +00:00
|
|
|
/** Registers a resume callback */
|
2012-08-17 01:50:38 +00:00
|
|
|
extern void usbd_register_resume_callback(usbd_device *usbd_dev,
|
|
|
|
void (*callback)(void));
|
2015-10-13 18:22:33 +00:00
|
|
|
/** Registers a SOF callback */
|
2012-08-17 01:50:38 +00:00
|
|
|
extern void usbd_register_sof_callback(usbd_device *usbd_dev,
|
|
|
|
void (*callback)(void));
|
|
|
|
|
2015-07-29 21:11:26 +00:00
|
|
|
typedef void (*usbd_control_complete_callback)(usbd_device *usbd_dev,
|
2015-05-26 22:12:09 +00:00
|
|
|
struct usb_setup_data *req);
|
|
|
|
|
2015-05-26 22:19:51 +00:00
|
|
|
typedef enum usbd_request_return_codes (*usbd_control_callback)(
|
|
|
|
usbd_device *usbd_dev,
|
2013-06-13 02:11:22 +00:00
|
|
|
struct usb_setup_data *req, uint8_t **buf, uint16_t *len,
|
2015-05-26 22:12:09 +00:00
|
|
|
usbd_control_complete_callback *complete);
|
|
|
|
|
2015-12-14 21:57:15 +00:00
|
|
|
typedef void (*usbd_set_config_callback)(usbd_device *usbd_dev,
|
|
|
|
uint16_t wValue);
|
2015-05-26 22:12:09 +00:00
|
|
|
|
|
|
|
typedef void (*usbd_set_altsetting_callback)(usbd_device *usbd_dev,
|
2015-12-14 21:57:15 +00:00
|
|
|
uint16_t wIndex, uint16_t wValue);
|
2015-05-26 22:12:09 +00:00
|
|
|
|
|
|
|
typedef void (*usbd_endpoint_callback)(usbd_device *usbd_dev, uint8_t ep);
|
2010-11-05 23:21:46 +00:00
|
|
|
|
2010-11-02 01:02:21 +00:00
|
|
|
/* <usb_control.c> */
|
2015-10-13 18:22:33 +00:00
|
|
|
/** Registers a control callback.
|
|
|
|
*
|
2018-01-04 16:23:17 +00:00
|
|
|
* 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)).
|
|
|
|
* @sa usbd_register_set_config_callback
|
2019-06-11 20:56:38 +00:00
|
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
2015-10-13 18:22:33 +00:00
|
|
|
* @param type Handled request type
|
|
|
|
* @param type_mask Mask to apply before matching request type
|
2019-06-11 20:56:38 +00:00
|
|
|
* @param callback your desired callback function
|
2015-10-13 18:22:33 +00:00
|
|
|
* @return 0 if successful
|
|
|
|
*/
|
2013-06-13 02:11:22 +00:00
|
|
|
extern int usbd_register_control_callback(usbd_device *usbd_dev, uint8_t type,
|
|
|
|
uint8_t type_mask,
|
2012-08-17 01:50:38 +00:00
|
|
|
usbd_control_callback callback);
|
2010-11-02 01:02:21 +00:00
|
|
|
|
|
|
|
/* <usb_standard.c> */
|
2015-10-13 18:22:33 +00:00
|
|
|
/** Registers a "Set Config" callback
|
2019-06-11 20:56:38 +00:00
|
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
|
|
|
* @param callback your desired callback function
|
2018-07-25 22:11:25 +00:00
|
|
|
* @return 0 if successful or already existed.
|
|
|
|
* @return -1 if no more space was available for callbacks.
|
2015-10-13 18:22:33 +00:00
|
|
|
*/
|
2014-07-14 12:50:07 +00:00
|
|
|
extern int usbd_register_set_config_callback(usbd_device *usbd_dev,
|
2015-05-26 22:12:09 +00:00
|
|
|
usbd_set_config_callback callback);
|
2019-06-11 20:56:38 +00:00
|
|
|
/** Registers a "Set Interface" (alternate setting) callback
|
|
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
|
|
|
* @param callback your desired callback function
|
|
|
|
*/
|
2012-11-16 00:02:36 +00:00
|
|
|
extern void usbd_register_set_altsetting_callback(usbd_device *usbd_dev,
|
2015-12-14 21:57:15 +00:00
|
|
|
usbd_set_altsetting_callback callback);
|
2012-11-16 00:02:36 +00:00
|
|
|
|
2020-10-17 17:12:20 +00:00
|
|
|
/** Registers a non-contiguous string descriptor */
|
|
|
|
extern void usbd_register_extra_string(usbd_device *usbd_dev, int index, const char* string);
|
|
|
|
|
2010-11-02 01:02:21 +00:00
|
|
|
/* Functions to be provided by the hardware abstraction layer */
|
2012-08-17 01:50:38 +00:00
|
|
|
extern void usbd_poll(usbd_device *usbd_dev);
|
2015-10-13 18:22:33 +00:00
|
|
|
|
2018-05-26 12:59:14 +00:00
|
|
|
/** 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.)
|
2019-06-11 20:56:38 +00:00
|
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
|
|
|
* @param disconnected true to request a disconnect
|
2018-05-26 12:59:14 +00:00
|
|
|
*/
|
2012-08-17 01:50:38 +00:00
|
|
|
extern void usbd_disconnect(usbd_device *usbd_dev, bool disconnected);
|
2010-11-02 01:02:21 +00:00
|
|
|
|
2015-10-13 18:22:33 +00:00
|
|
|
/** Setup an endpoint
|
2019-06-11 20:56:38 +00:00
|
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
2015-10-13 18:22:33 +00:00
|
|
|
* @param addr Full EP address including direction (e.g. 0x01 or 0x81)
|
|
|
|
* @param type Value for bmAttributes (USB_ENDPOINT_ATTR_*)
|
2019-06-11 20:56:38 +00:00
|
|
|
* @param max_size Endpoint max size
|
|
|
|
* @param callback your desired callback function
|
2019-06-05 21:48:28 +00:00
|
|
|
* @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.
|
2015-10-13 18:22:33 +00:00
|
|
|
*/
|
2013-06-13 04:00:50 +00:00
|
|
|
extern void usbd_ep_setup(usbd_device *usbd_dev, uint8_t addr, uint8_t type,
|
2015-05-26 22:12:09 +00:00
|
|
|
uint16_t max_size, usbd_endpoint_callback callback);
|
2010-11-02 01:02:21 +00:00
|
|
|
|
2015-10-13 18:22:33 +00:00
|
|
|
/** Write a packet
|
2019-06-11 20:56:38 +00:00
|
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
2015-10-13 18:22:33 +00:00
|
|
|
* @param addr EP address (direction is ignored)
|
2019-06-11 20:56:38 +00:00
|
|
|
* @param buf pointer to user data to write
|
2015-10-13 18:22:33 +00:00
|
|
|
* @param len # of bytes
|
2015-12-11 16:46:44 +00:00
|
|
|
* @return 0 if failed, len if successful
|
2015-10-13 18:22:33 +00:00
|
|
|
*/
|
2013-06-13 02:11:22 +00:00
|
|
|
extern uint16_t usbd_ep_write_packet(usbd_device *usbd_dev, uint8_t addr,
|
|
|
|
const void *buf, uint16_t len);
|
2010-11-02 01:02:21 +00:00
|
|
|
|
2015-10-13 18:22:33 +00:00
|
|
|
/** Read a packet
|
2019-06-11 20:56:38 +00:00
|
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
2015-10-13 18:22:33 +00:00
|
|
|
* @param addr EP address
|
2019-06-11 20:56:38 +00:00
|
|
|
* @param buf user buffer that will receive data
|
2015-10-13 18:22:33 +00:00
|
|
|
* @param len # of bytes
|
|
|
|
* @return Actual # of bytes read
|
|
|
|
*/
|
2013-06-13 02:11:22 +00:00
|
|
|
extern uint16_t usbd_ep_read_packet(usbd_device *usbd_dev, uint8_t addr,
|
|
|
|
void *buf, uint16_t len);
|
2015-10-13 18:22:33 +00:00
|
|
|
/** Set/clear STALL condition on an endpoint
|
2019-06-11 20:56:38 +00:00
|
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
2015-10-13 18:22:33 +00:00
|
|
|
* @param addr Full EP address (with direction bit)
|
|
|
|
* @param stall if 0, clear STALL, else set stall.
|
|
|
|
*/
|
2013-06-13 04:00:50 +00:00
|
|
|
extern void usbd_ep_stall_set(usbd_device *usbd_dev, uint8_t addr,
|
|
|
|
uint8_t stall);
|
2015-10-13 18:22:33 +00:00
|
|
|
|
|
|
|
/** Get STALL status of an endpoint
|
2019-06-11 20:56:38 +00:00
|
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
2015-10-13 18:22:33 +00:00
|
|
|
* @param addr Full EP address (with direction bit)
|
|
|
|
* @return nonzero if endpoint is stalled
|
|
|
|
*/
|
2013-06-13 02:11:22 +00:00
|
|
|
extern uint8_t usbd_ep_stall_get(usbd_device *usbd_dev, uint8_t addr);
|
2010-11-02 01:02:21 +00:00
|
|
|
|
2015-10-13 18:22:33 +00:00
|
|
|
/** Set an Out endpoint to NAK
|
2019-06-11 20:56:38 +00:00
|
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
2015-10-13 18:22:33 +00:00
|
|
|
* @param addr EP address
|
|
|
|
* @param nak if nonzero, set NAK
|
|
|
|
*/
|
2013-06-13 02:11:22 +00:00
|
|
|
extern void usbd_ep_nak_set(usbd_device *usbd_dev, uint8_t addr, uint8_t nak);
|
2011-03-29 18:17:02 +00:00
|
|
|
|
2012-09-02 15:12:58 +00:00
|
|
|
END_DECLS
|
|
|
|
|
2010-11-02 01:02:21 +00:00
|
|
|
#endif
|
2013-03-10 23:06:57 +00:00
|
|
|
|
|
|
|
/**@}*/
|
|
|
|
|