244 lines
8.9 KiB
C
244 lines
8.9 KiB
C
/** @defgroup usb_driver_defines USB Drivers
|
|
|
|
@brief <b>Defined Constants and Types for the USB Drivers</b>
|
|
|
|
@ingroup USB_defines
|
|
|
|
@version 1.0.0
|
|
|
|
@author @htmlonly © @endhtmlonly 2010
|
|
Gareth McMullin <gareth@blacksphere.co.nz>
|
|
|
|
@date 10 March 2013
|
|
|
|
LGPL License Terms @ref lgpl_license
|
|
*/
|
|
|
|
/*
|
|
* This file is part of the libopencm3 project.
|
|
*
|
|
* Copyright (C) 2010 Gareth McMullin <gareth@blacksphere.co.nz>
|
|
*
|
|
* 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
|
|
* the Free Software Foundation, either version 3 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This library is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU Lesser General Public License for more details.
|
|
*
|
|
* 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/>.
|
|
*/
|
|
|
|
/**@{*/
|
|
|
|
#ifndef __USBD_H
|
|
#define __USBD_H
|
|
|
|
#include <libopencm3/usb/usbstd.h>
|
|
|
|
BEGIN_DECLS
|
|
|
|
|
|
enum usbd_request_return_codes {
|
|
USBD_REQ_NOTSUPP = 0,
|
|
USBD_REQ_HANDLED = 1,
|
|
USBD_REQ_NEXT_CALLBACK = 2,
|
|
};
|
|
|
|
typedef struct _usbd_driver usbd_driver;
|
|
typedef struct _usbd_device usbd_device;
|
|
|
|
extern const usbd_driver st_usbfs_v1_usb_driver;
|
|
extern const usbd_driver stm32f107_usb_driver;
|
|
extern const usbd_driver stm32f207_usb_driver;
|
|
extern const usbd_driver st_usbfs_v2_usb_driver;
|
|
#define otgfs_usb_driver stm32f107_usb_driver
|
|
#define otghs_usb_driver stm32f207_usb_driver
|
|
extern const usbd_driver efm32lg_usb_driver;
|
|
extern const usbd_driver efm32hg_usb_driver;
|
|
extern const usbd_driver lm4f_usb_driver;
|
|
|
|
/* <usb.c> */
|
|
/**
|
|
* 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.
|
|
* @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.
|
|
* @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).
|
|
*
|
|
* 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.
|
|
*/
|
|
extern 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);
|
|
|
|
/** Registers a reset callback */
|
|
extern void usbd_register_reset_callback(usbd_device *usbd_dev,
|
|
void (*callback)(void));
|
|
/** Registers a suspend callback */
|
|
extern void usbd_register_suspend_callback(usbd_device *usbd_dev,
|
|
void (*callback)(void));
|
|
/** Registers a resume callback */
|
|
extern void usbd_register_resume_callback(usbd_device *usbd_dev,
|
|
void (*callback)(void));
|
|
/** Registers a SOF callback */
|
|
extern void usbd_register_sof_callback(usbd_device *usbd_dev,
|
|
void (*callback)(void));
|
|
|
|
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);
|
|
|
|
/* <usb_control.c> */
|
|
/** 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)).
|
|
* @sa usbd_register_set_config_callback
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
|
* @param type Handled request type
|
|
* @param type_mask Mask to apply before matching request type
|
|
* @param callback your desired callback function
|
|
* @return 0 if successful
|
|
*/
|
|
extern int usbd_register_control_callback(usbd_device *usbd_dev, uint8_t type,
|
|
uint8_t type_mask,
|
|
usbd_control_callback callback);
|
|
|
|
/* <usb_standard.c> */
|
|
/** Registers a "Set Config" callback
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
|
* @param callback your desired callback function
|
|
* @return 0 if successful or already existed.
|
|
* @return -1 if no more space was available for callbacks.
|
|
*/
|
|
extern int usbd_register_set_config_callback(usbd_device *usbd_dev,
|
|
usbd_set_config_callback callback);
|
|
/** 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
|
|
*/
|
|
extern void usbd_register_set_altsetting_callback(usbd_device *usbd_dev,
|
|
usbd_set_altsetting_callback callback);
|
|
|
|
/** Registers a non-contiguous string descriptor */
|
|
extern void usbd_register_extra_string(usbd_device *usbd_dev, int index, const char* string);
|
|
|
|
/* Functions to be provided by the hardware abstraction layer */
|
|
extern void usbd_poll(usbd_device *usbd_dev);
|
|
|
|
/** 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.)
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
|
* @param disconnected true to request a disconnect
|
|
*/
|
|
extern void usbd_disconnect(usbd_device *usbd_dev, bool disconnected);
|
|
|
|
/** Setup an endpoint
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
|
* @param addr Full EP address including direction (e.g. 0x01 or 0x81)
|
|
* @param type Value for bmAttributes (USB_ENDPOINT_ATTR_*)
|
|
* @param max_size Endpoint max size
|
|
* @param callback your 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.
|
|
*/
|
|
extern void usbd_ep_setup(usbd_device *usbd_dev, uint8_t addr, uint8_t type,
|
|
uint16_t max_size, usbd_endpoint_callback callback);
|
|
|
|
/** Write a packet
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
|
* @param addr EP address (direction is ignored)
|
|
* @param buf pointer to user data to write
|
|
* @param len # of bytes
|
|
* @return 0 if failed, len if successful
|
|
*/
|
|
extern uint16_t usbd_ep_write_packet(usbd_device *usbd_dev, uint8_t addr,
|
|
const void *buf, uint16_t len);
|
|
|
|
/** Read a packet
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
|
* @param addr EP address
|
|
* @param buf user buffer that will receive data
|
|
* @param len # of bytes
|
|
* @return Actual # of bytes read
|
|
*/
|
|
extern uint16_t usbd_ep_read_packet(usbd_device *usbd_dev, uint8_t addr,
|
|
void *buf, uint16_t len);
|
|
/** Set/clear STALL condition on an endpoint
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
|
* @param addr Full EP address (with direction bit)
|
|
* @param stall if 0, clear STALL, else set stall.
|
|
*/
|
|
extern void usbd_ep_stall_set(usbd_device *usbd_dev, uint8_t addr,
|
|
uint8_t stall);
|
|
|
|
/** Get STALL status of an endpoint
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
|
* @param addr Full EP address (with direction bit)
|
|
* @return nonzero if endpoint is stalled
|
|
*/
|
|
extern uint8_t usbd_ep_stall_get(usbd_device *usbd_dev, uint8_t addr);
|
|
|
|
/** Set an Out endpoint to NAK
|
|
* @param usbd_dev the usb device handle returned from @ref usbd_init
|
|
* @param addr EP address
|
|
* @param nak if nonzero, set NAK
|
|
*/
|
|
extern void usbd_ep_nak_set(usbd_device *usbd_dev, uint8_t addr, uint8_t nak);
|
|
|
|
END_DECLS
|
|
|
|
#endif
|
|
|
|
/**@}*/
|
|
|