libopencm3
A free/libre/open-source firmware library for various ARM Cortex-M3 microcontrollers.
usbd.h
Go to the documentation of this file.
1/** @defgroup usb_driver_defines USB Drivers
2
3@brief <b>Defined Constants and Types for the USB Drivers</b>
4
5@ingroup USB_defines
6
7@version 1.0.0
8
9@author @htmlonly &copy; @endhtmlonly 2010
10Gareth McMullin <gareth@blacksphere.co.nz>
11
12@date 10 March 2013
13
14LGPL License Terms @ref lgpl_license
15*/
16
17/*
18 * This file is part of the libopencm3 project.
19 *
20 * Copyright (C) 2010 Gareth McMullin <gareth@blacksphere.co.nz>
21 *
22 * This library is free software: you can redistribute it and/or modify
23 * it under the terms of the GNU Lesser General Public License as published by
24 * the Free Software Foundation, either version 3 of the License, or
25 * (at your option) any later version.
26 *
27 * This library is distributed in the hope that it will be useful,
28 * but WITHOUT ANY WARRANTY; without even the implied warranty of
29 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
30 * GNU Lesser General Public License for more details.
31 *
32 * You should have received a copy of the GNU Lesser General Public License
33 * along with this library. If not, see <http://www.gnu.org/licenses/>.
34 */
35
36/**@{*/
37
38#ifndef __USBD_H
39#define __USBD_H
40
42
44
45
50};
51
52typedef struct _usbd_driver usbd_driver;
53typedef struct _usbd_device usbd_device;
54
59#define otgfs_usb_driver stm32f107_usb_driver
60#define otghs_usb_driver stm32f207_usb_driver
63extern const usbd_driver lm4f_usb_driver;
64
65/* <usb.c> */
66/**
67 * Main initialization entry point.
68 *
69 * Initialize the USB firmware library to implement the USB device described
70 * by the descriptors provided.
71 *
72 * It is required that the 48MHz USB clock is already available.
73 *
74 * @param driver TODO
75 * @param dev Pointer to USB device descriptor. This must not be changed while
76 * the device is in use.
77 * @param conf Pointer to array of USB configuration descriptors. These must
78 * not be changed while the device is in use. The length of this
79 * array is determined by the bNumConfigurations field in the
80 * device descriptor.
81 * @param strings Pointer to an array of strings for USB string descriptors.
82 * Referenced in @e iSomething fields, e.g. @a iManufacturer.
83 * Since a zero index means "no string", an iSomething value of
84 * 1 refers strings[0].
85 * @param num_strings Number of items in @a strings array.
86 * @param control_buffer Pointer to array that would hold the data
87 * received during control requests with DATA
88 * stage
89 * @param control_buffer_size Size of control_buffer
90 * @return the usb device initialized for use. (currently cannot fail).
91 *
92 * To place @a strings entirely into Flash/read-only memory, use
93 * @code static const * const strings[] = { ... }; @endcode
94 * (note the double @e const.) The first @e const refers to the strings
95 * while the second @e const refers to the array.
96 */
97extern usbd_device * usbd_init(const usbd_driver *driver,
98 const struct usb_device_descriptor *dev,
99 const struct usb_config_descriptor *conf,
100 const char * const *strings, int num_strings,
101 uint8_t *control_buffer,
102 uint16_t control_buffer_size);
103
104/** Registers a reset callback */
105extern void usbd_register_reset_callback(usbd_device *usbd_dev,
106 void (*callback)(void));
107/** Registers a suspend callback */
108extern void usbd_register_suspend_callback(usbd_device *usbd_dev,
109 void (*callback)(void));
110/** Registers a resume callback */
111extern void usbd_register_resume_callback(usbd_device *usbd_dev,
112 void (*callback)(void));
113/** Registers a SOF callback */
114extern void usbd_register_sof_callback(usbd_device *usbd_dev,
115 void (*callback)(void));
116
118 struct usb_setup_data *req);
119
121 usbd_device *usbd_dev,
122 struct usb_setup_data *req, uint8_t **buf, uint16_t *len,
124
125typedef void (*usbd_set_config_callback)(usbd_device *usbd_dev,
126 uint16_t wValue);
127
129 uint16_t wIndex, uint16_t wValue);
130
131typedef void (*usbd_endpoint_callback)(usbd_device *usbd_dev, uint8_t ep);
132
133/* <usb_control.c> */
134/** Registers a control callback.
135 *
136 * Since the list of user control callbacks is cleared every time
137 * device configuration is set (inside usb_standard_set_configuration()),
138 * control callback registration must happen inside (or after) the
139 * config callback. The specified callback will be called if
140 * (type == (bmRequestType & type_mask)).
141 * @sa usbd_register_set_config_callback
142 * @param usbd_dev the usb device handle returned from @ref usbd_init
143 * @param type Handled request type
144 * @param type_mask Mask to apply before matching request type
145 * @param callback your desired callback function
146 * @return 0 if successful
147 */
148extern int usbd_register_control_callback(usbd_device *usbd_dev, uint8_t type,
149 uint8_t type_mask,
150 usbd_control_callback callback);
151
152/* <usb_standard.c> */
153/** Registers a "Set Config" callback
154 * @param usbd_dev the usb device handle returned from @ref usbd_init
155 * @param callback your desired callback function
156 * @return 0 if successful or already existed.
157 * @return -1 if no more space was available for callbacks.
158 */
160 usbd_set_config_callback callback);
161/** Registers a "Set Interface" (alternate setting) callback
162 * @param usbd_dev the usb device handle returned from @ref usbd_init
163 * @param callback your desired callback function
164 */
167
168/** Registers a non-contiguous string descriptor */
169extern void usbd_register_extra_string(usbd_device *usbd_dev, int index, const char* string);
170
171/* Functions to be provided by the hardware abstraction layer */
172extern void usbd_poll(usbd_device *usbd_dev);
173
174/** Disconnect, if supported by the driver
175 *
176 * This function is implemented as weak function and can be replaced by an
177 * application specific version to handle chips that don't have built-in
178 * handling for this (e.g. STM32F1.)
179 * @param usbd_dev the usb device handle returned from @ref usbd_init
180 * @param disconnected true to request a disconnect
181 */
182extern void usbd_disconnect(usbd_device *usbd_dev, bool disconnected);
183
184/** Setup an endpoint
185 * @param usbd_dev the usb device handle returned from @ref usbd_init
186 * @param addr Full EP address including direction (e.g. 0x01 or 0x81)
187 * @param type Value for bmAttributes (USB_ENDPOINT_ATTR_*)
188 * @param max_size Endpoint max size
189 * @param callback your desired callback function
190 * @note The stack only supports 8 endpoints, 0..7, so don't try
191 * and use arbitrary addresses here, even though USB itself would allow this.
192 * Not all backends support arbitrary addressing anyway.
193 */
194extern void usbd_ep_setup(usbd_device *usbd_dev, uint8_t addr, uint8_t type,
195 uint16_t max_size, usbd_endpoint_callback callback);
196
197/** Write a packet
198 * @param usbd_dev the usb device handle returned from @ref usbd_init
199 * @param addr EP address (direction is ignored)
200 * @param buf pointer to user data to write
201 * @param len # of bytes
202 * @return 0 if failed, len if successful
203 */
204extern uint16_t usbd_ep_write_packet(usbd_device *usbd_dev, uint8_t addr,
205 const void *buf, uint16_t len);
206
207/** Read a packet
208 * @param usbd_dev the usb device handle returned from @ref usbd_init
209 * @param addr EP address
210 * @param buf user buffer that will receive data
211 * @param len # of bytes
212 * @return Actual # of bytes read
213 */
214extern uint16_t usbd_ep_read_packet(usbd_device *usbd_dev, uint8_t addr,
215 void *buf, uint16_t len);
216/** Set/clear STALL condition on an endpoint
217 * @param usbd_dev the usb device handle returned from @ref usbd_init
218 * @param addr Full EP address (with direction bit)
219 * @param stall if 0, clear STALL, else set stall.
220 */
221extern void usbd_ep_stall_set(usbd_device *usbd_dev, uint8_t addr,
222 uint8_t stall);
223
224/** Get STALL status of an endpoint
225 * @param usbd_dev the usb device handle returned from @ref usbd_init
226 * @param addr Full EP address (with direction bit)
227 * @return nonzero if endpoint is stalled
228 */
229extern uint8_t usbd_ep_stall_get(usbd_device *usbd_dev, uint8_t addr);
230
231/** Set an Out endpoint to NAK
232 * @param usbd_dev the usb device handle returned from @ref usbd_init
233 * @param addr EP address
234 * @param nak if nonzero, set NAK
235 */
236extern void usbd_ep_nak_set(usbd_device *usbd_dev, uint8_t addr, uint8_t nak);
237
239
240#endif
241
242/**@}*/
243
#define END_DECLS
Definition: common.h:34
#define BEGIN_DECLS
Definition: common.h:33
void usbd_register_resume_callback(usbd_device *usbd_dev, void(*callback)(void))
Registers a resume callback.
Definition: usb.c:88
void usbd_register_suspend_callback(usbd_device *usbd_dev, void(*callback)(void))
Registers a suspend callback.
Definition: usb.c:82
const usbd_driver stm32f207_usb_driver
void usbd_register_reset_callback(usbd_device *usbd_dev, void(*callback)(void))
Registers a reset callback.
Definition: usb.c:77
void usbd_ep_nak_set(usbd_device *usbd_dev, uint8_t addr, uint8_t nak)
Set an Out endpoint to NAK.
Definition: usb.c:168
const usbd_driver st_usbfs_v2_usb_driver
Definition: st_usbfs_v2.c:99
uint8_t usbd_ep_stall_get(usbd_device *usbd_dev, uint8_t addr)
Get STALL status of an endpoint.
Definition: usb.c:163
struct _usbd_device usbd_device
Definition: usbd.h:53
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.
Definition: usb.c:42
const usbd_driver stm32f107_usb_driver
const usbd_driver efm32hg_usb_driver
void usbd_ep_stall_set(usbd_device *usbd_dev, uint8_t addr, uint8_t stall)
Set/clear STALL condition on an endpoint.
Definition: usb.c:158
int usbd_register_control_callback(usbd_device *usbd_dev, uint8_t type, uint8_t type_mask, usbd_control_callback callback)
Registers a control callback.
Definition: usb_control.c:73
void usbd_poll(usbd_device *usbd_dev)
Definition: usb.c:126
const usbd_driver lm4f_usb_driver
uint16_t usbd_ep_write_packet(usbd_device *usbd_dev, uint8_t addr, const void *buf, uint16_t len)
Write a packet.
Definition: usb.c:146
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.
Definition: usb.c:140
uint16_t usbd_ep_read_packet(usbd_device *usbd_dev, uint8_t addr, void *buf, uint16_t len)
Read a packet.
Definition: usb.c:152
const usbd_driver st_usbfs_v1_usb_driver
int usbd_register_set_config_callback(usbd_device *usbd_dev, usbd_set_config_callback callback)
Registers a "Set Config" callback.
Definition: usb_standard.c:42
void usbd_register_set_altsetting_callback(usbd_device *usbd_dev, usbd_set_altsetting_callback callback)
Registers a "Set Interface" (alternate setting) callback.
Definition: usb_standard.c:62
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: usbd.h:120
void usbd_register_sof_callback(usbd_device *usbd_dev, void(*callback)(void))
Registers a SOF callback.
Definition: usb.c:94
void(* usbd_endpoint_callback)(usbd_device *usbd_dev, uint8_t ep)
Definition: usbd.h:131
usbd_request_return_codes
Definition: usbd.h:46
void(* usbd_set_config_callback)(usbd_device *usbd_dev, uint16_t wValue)
Definition: usbd.h:125
void usbd_register_extra_string(usbd_device *usbd_dev, int index, const char *string)
Registers a non-contiguous string descriptor.
Definition: usb.c:99
void(* usbd_set_altsetting_callback)(usbd_device *usbd_dev, uint16_t wIndex, uint16_t wValue)
Definition: usbd.h:128
void usbd_disconnect(usbd_device *usbd_dev, bool disconnected)
Disconnect, if supported by the driver.
Definition: usb.c:131
const usbd_driver efm32lg_usb_driver
void(* usbd_control_complete_callback)(usbd_device *usbd_dev, struct usb_setup_data *req)
Definition: usbd.h:117
struct _usbd_driver usbd_driver
Definition: usbd.h:52
@ USBD_REQ_NEXT_CALLBACK
Definition: usbd.h:49
@ USBD_REQ_HANDLED
Definition: usbd.h:48
@ USBD_REQ_NOTSUPP
Definition: usbd.h:47
uint16_t wIndex
Definition: usbstd.h:60
uint16_t wValue
Definition: usbstd.h:59