OpenOCD
usb.h
Go to the documentation of this file.
1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 
3 /***************************************************************************
4  * Copyright (C) 2011 by Martin Schmoelzer *
5  * <martin.schmoelzer@student.tuwien.ac.at> *
6  ***************************************************************************/
7 
8 #ifndef __USB_H
9 #define __USB_H
10 
11 #include "reg_ezusb.h"
12 
13 #include <stdint.h>
14 #include <stdbool.h>
15 
16 #define NULL (void *)0;
17 
18 /* High and Low byte of a word (uint16_t) */
19 #define HI8(word) (uint8_t)(((uint16_t)word >> 8) & 0xff)
20 #define LO8(word) (uint8_t)((uint16_t)word & 0xff)
21 
22 /* Convenience functions */
23 #define STALL_EP0() (EP0CS |= EP0STALL)
24 #define CLEAR_IRQ() (EXIF &= ~USBINT)
25 
26 /*********** USB descriptors. See section 9.5 of the USB 1.1 spec **********/
27 
28 /* USB Descriptor Types. See USB 1.1 spec, page 187, table 9-5 */
29 #define DESCRIPTOR_TYPE_DEVICE 0x01
30 #define DESCRIPTOR_TYPE_CONFIGURATION 0x02
31 #define DESCRIPTOR_TYPE_STRING 0x03
32 #define DESCRIPTOR_TYPE_INTERFACE 0x04
33 #define DESCRIPTOR_TYPE_ENDPOINT 0x05
34 
35 #define STR_DESCR(len, ...) { len * 2 + 2, DESCRIPTOR_TYPE_STRING, { __VA_ARGS__ } }
36 
39  uint8_t bLength;
40  uint8_t bDescriptorType;
41  uint16_t bcdUSB;
42  uint8_t bDeviceClass;
43  uint8_t bDeviceSubClass;
44  uint8_t bDeviceProtocol;
45  uint8_t bMaxPacketSize0;
46  uint16_t idVendor;
47  uint16_t idProduct;
48  uint16_t bcdDevice;
49  uint8_t iManufacturer;
50  uint8_t iProduct;
51  uint8_t iSerialNumber;
53 };
54 
57  uint8_t bLength;
58  uint8_t bDescriptorType;
59  uint16_t wTotalLength;
60  uint8_t bNumInterfaces;
62  uint8_t iConfiguration;
63  uint8_t bmAttributes;
64  uint8_t MaxPower;
65 };
66 
69  uint8_t bLength;
70  uint8_t bDescriptorType;
71  uint8_t bInterfaceNumber;
73  uint8_t bNumEndpoints;
74  uint8_t bInterfaceClass;
77  uint8_t iInterface;
78 };
79 
82  uint8_t bLength;
83  uint8_t bDescriptorType;
84  uint8_t bEndpointAddress;
85  uint8_t bmAttributes;
86  uint16_t wMaxPacketSize;
87  uint8_t bInterval;
88 };
89 
92  uint8_t bLength;
93  uint8_t bDescriptorType;
94  uint16_t wLANGID[];
95 };
96 
99  uint8_t bLength;
100  uint8_t bDescriptorType;
101  uint16_t bString[];
102 };
103 
104 /********************** USB Control Endpoint 0 related *********************/
105 
107 struct setup_data {
108  uint8_t bmRequestType;
109  uint8_t bRequest;
110  uint16_t wValue;
111  uint16_t wIndex;
112  uint16_t wLength;
113 };
114 
115 /* External declarations for variables that need to be accessed outside of
116  * the USB module */
117 extern volatile bool EP2_out;
118 extern volatile bool EP2_in;
119 extern volatile __xdata __at 0x7FE8 struct setup_data setup_data;
120 
121 /*
122  * USB Request Types (bmRequestType): See USB 1.1 spec, page 183, table 9-2
123  *
124  * Bit 7: Data transfer direction
125  * 0 = Host-to-device
126  * 1 = Device-to-host
127  * Bit 6...5: Type
128  * 0 = Standard
129  * 1 = Class
130  * 2 = Vendor
131  * 3 = Reserved
132  * Bit 4...0: Recipient
133  * 0 = Device
134  * 1 = Interface
135  * 2 = Endpoint
136  * 3 = Other
137  * 4...31 = Reserved
138  */
139 
140 #define USB_DIR_OUT 0x00
141 #define USB_DIR_IN 0x80
142 
143 #define USB_REQ_TYPE_STANDARD (0x00 << 5)
144 #define USB_REQ_TYPE_CLASS (0x01 << 5)
145 #define USB_REQ_TYPE_VENDOR (0x02 << 5)
146 #define USB_REQ_TYPE_RESERVED (0x03 << 5)
147 
148 #define USB_RECIP_DEVICE 0x00
149 #define USB_RECIP_INTERFACE 0x01
150 #define USB_RECIP_ENDPOINT 0x02
151 #define USB_RECIP_OTHER 0x03
152 
153 /* bmRequestType for USB Standard Requests */
154 
155 /* Clear Interface Request */
156 #define CF_DEVICE (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
157 #define CF_INTERFACE (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_INTERFACE)
158 #define CF_ENDPOINT (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_ENDPOINT)
159 
160 /* Get Configuration Request */
161 #define GC_DEVICE (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
162 
163 /* Get Descriptor Request */
164 #define GD_DEVICE (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
165 
166 /* Get Interface Request */
167 #define GI_INTERFACE (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_INTERFACE)
168 
169 /* Get Status Request: See USB 1.1 spec, page 190 */
170 #define GS_DEVICE (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
171 #define GS_INTERFACE (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_INTERFACE)
172 #define GS_ENDPOINT (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_ENDPOINT)
173 
174 /* Set Address Request is handled by EZ-USB core */
175 
176 /* Set Configuration Request */
177 #define SC_DEVICE (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
178 
179 /* Set Descriptor Request */
180 #define SD_DEVICE (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
181 
182 /* Set Feature Request */
183 #define SF_DEVICE (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_DEVICE)
184 #define SF_INTERFACE (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_INTERFACE)
185 #define SF_ENDPOINT (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_ENDPOINT)
186 
187 /* Set Interface Request */
188 #define SI_INTERFACE (USB_DIR_OUT | USB_REQ_TYPE_STANDARD | USB_RECIP_INTERFACE)
189 
190 /* Synch Frame Request */
191 #define SY_ENDPOINT (USB_DIR_IN | USB_REQ_TYPE_STANDARD | USB_RECIP_ENDPOINT)
192 
193 /* USB Requests (bRequest): See USB 1.1 spec, table 9-4 on page 187 */
194 #define GET_STATUS 0
195 #define CLEAR_FEATURE 1
196 /* Value '2' is reserved for future use */
197 #define SET_FEATURE 3
198 /* Value '4' is reserved for future use */
199 #define SET_ADDRESS 5
200 #define GET_DESCRIPTOR 6
201 #define SET_DESCRIPTOR 7
202 #define GET_CONFIGURATION 8
203 #define SET_CONFIGURATION 9
204 #define GET_INTERFACE 10
205 #define SET_INTERFACE 11
206 #define SYNCH_FRAME 12
207 
208 /* Standard Feature Selectors: See USB 1.1 spec, table 9-6 on page 188 */
209 #define DEVICE_REMOTE_WAKEUP 1
210 #define ENDPOINT_HALT 0
211 
212 /************************** EZ-USB specific stuff **************************/
213 
215 enum usb_isr {
216  SUDAV_ISR = 13,
237  EP7OUT_ISR
238 };
239 
240 /*************************** Function Prototypes ***************************/
241 
242 __xdata uint8_t *usb_get_endpoint_cs_reg(uint8_t ep);
243 void usb_reset_data_toggle(uint8_t ep);
244 
245 bool usb_handle_get_status(void);
246 bool usb_handle_clear_feature(void);
247 bool usb_handle_set_feature(void);
248 bool usb_handle_get_descriptor(void);
249 void usb_handle_set_interface(void);
250 
251 void usb_handle_setup_data(void);
252 void usb_init(void);
253 
254 #endif
All information in this file was taken from the EZ-USB Technical Reference Manual,...
USB Control Setup Data.
Definition: usb.h:107
uint16_t wIndex
Field that varies according to request.
Definition: usb.h:111
uint8_t bRequest
Specific request.
Definition: usb.h:109
uint8_t bmRequestType
Characteristics of a request.
Definition: usb.h:108
uint16_t wValue
Field that varies according to request.
Definition: usb.h:110
uint16_t wLength
Number of bytes to transfer in data stage.
Definition: usb.h:112
USB Configuration Descriptor.
Definition: usb.h:56
uint16_t wTotalLength
Combined total length of all descriptors.
Definition: usb.h:59
uint8_t MaxPower
Maximum power consumption in 2 mA units.
Definition: usb.h:64
uint8_t bDescriptorType
CONFIGURATION descriptor type.
Definition: usb.h:58
uint8_t bNumInterfaces
Number of interfaces in this configuration.
Definition: usb.h:60
uint8_t bmAttributes
Configuration characteristics.
Definition: usb.h:63
uint8_t bLength
Size of this descriptor in bytes.
Definition: usb.h:57
uint8_t iConfiguration
Index of configuration string descriptor.
Definition: usb.h:62
uint8_t bConfigurationValue
Value used to select this configuration.
Definition: usb.h:61
USB Device Descriptor.
Definition: usb.h:38
uint16_t idVendor
USB Vendor ID.
Definition: usb.h:46
uint8_t iSerialNumber
Index of string descriptor containing serial #.
Definition: usb.h:51
uint16_t bcdDevice
Device Release Number (BCD).
Definition: usb.h:48
uint8_t bDeviceProtocol
Protocol code.
Definition: usb.h:44
uint8_t bNumConfigurations
Number of possible configurations.
Definition: usb.h:52
uint16_t idProduct
USB Product ID.
Definition: usb.h:47
uint16_t bcdUSB
USB specification release number (BCD).
Definition: usb.h:41
uint8_t bDeviceClass
Class code.
Definition: usb.h:42
uint8_t bMaxPacketSize0
Maximum packet size for EP0 (8, 16, 32, 64).
Definition: usb.h:45
uint8_t iProduct
Index of product string descriptor.
Definition: usb.h:50
uint8_t iManufacturer
Index of manufacturer string descriptor.
Definition: usb.h:49
uint8_t bDescriptorType
DEVICE Descriptor Type.
Definition: usb.h:40
uint8_t bDeviceSubClass
Subclass code.
Definition: usb.h:43
uint8_t bLength
Size of this descriptor in bytes.
Definition: usb.h:39
USB Endpoint Descriptor.
Definition: usb.h:81
uint16_t wMaxPacketSize
Maximum packet size for this endpoint.
Definition: usb.h:86
uint8_t bEndpointAddress
Endpoint Address: USB 1.1 spec, table 9-10.
Definition: usb.h:84
uint8_t bInterval
Polling interval (in ms) for this endpoint.
Definition: usb.h:87
uint8_t bmAttributes
Endpoint Attributes: USB 1.1 spec, table 9-10.
Definition: usb.h:85
uint8_t bDescriptorType
ENDPOINT descriptor type.
Definition: usb.h:83
uint8_t bLength
Size of this descriptor in bytes.
Definition: usb.h:82
USB Interface Descriptor.
Definition: usb.h:68
uint8_t bInterfaceProtocol
Protocol code.
Definition: usb.h:76
uint8_t bNumEndpoints
Number of endpoints used by this interface.
Definition: usb.h:73
uint8_t iInterface
Index of interface string descriptor.
Definition: usb.h:77
uint8_t bDescriptorType
INTERFACE descriptor type.
Definition: usb.h:70
uint8_t bLength
Size of this descriptor in bytes.
Definition: usb.h:69
uint8_t bInterfaceSubclass
Subclass code.
Definition: usb.h:75
uint8_t bAlternateSetting
Value used to select alternate setting.
Definition: usb.h:72
uint8_t bInterfaceClass
Class code.
Definition: usb.h:74
uint8_t bInterfaceNumber
Interface number.
Definition: usb.h:71
USB Language Descriptor.
Definition: usb.h:91
uint16_t wLANGID[]
LANGID codes.
Definition: usb.h:94
uint8_t bLength
Size of this descriptor in bytes.
Definition: usb.h:92
uint8_t bDescriptorType
STRING descriptor type.
Definition: usb.h:93
USB String Descriptor.
Definition: usb.h:98
uint8_t bDescriptorType
STRING descriptor type.
Definition: usb.h:100
uint8_t bLength
Size of this descriptor in bytes.
Definition: usb.h:99
uint16_t bString[]
UNICODE encoded string.
Definition: usb.h:101
bool usb_handle_clear_feature(void)
Handle CLEAR_FEATURE request.
Definition: usb.c:334
volatile bool EP2_out
Definition: usb.c:24
__xdata uint8_t * usb_get_endpoint_cs_reg(uint8_t ep)
Return the control/status register for an endpoint.
Definition: usb.c:221
void usb_handle_setup_data(void)
Handle the arrival of a USB Control Setup Packet.
Definition: usb.c:461
void usb_reset_data_toggle(uint8_t ep)
Definition: usb.c:256
void usb_handle_set_interface(void)
Handle SET_INTERFACE request.
Definition: usb.c:444
volatile bool EP2_in
Definition: usb.c:25
bool usb_handle_get_descriptor(void)
Handle GET_DESCRIPTOR request.
Definition: usb.c:403
bool usb_handle_get_status(void)
Handle GET_STATUS request.
Definition: usb.c:283
usb_isr
USB Interrupts.
Definition: usb.h:215
@ IBN_ISR
Definition: usb.h:221
@ EP3IN_ISR
Definition: usb.h:228
@ EP2OUT_ISR
Definition: usb.h:227
@ SUDAV_ISR
Definition: usb.h:216
@ EP7IN_ISR
Definition: usb.h:236
@ SUTOK_ISR
Definition: usb.h:218
@ EP1IN_ISR
Definition: usb.h:224
@ EP6IN_ISR
Definition: usb.h:234
@ SUSPEND_ISR
Definition: usb.h:219
@ EP1OUT_ISR
Definition: usb.h:225
@ USBRESET_ISR
Definition: usb.h:220
@ EP0OUT_ISR
Definition: usb.h:223
@ EP0IN_ISR
Definition: usb.h:222
@ EP5OUT_ISR
Definition: usb.h:233
@ EP4IN_ISR
Definition: usb.h:230
@ EP5IN_ISR
Definition: usb.h:232
@ EP6OUT_ISR
Definition: usb.h:235
@ EP4OUT_ISR
Definition: usb.h:231
@ EP2IN_ISR
Definition: usb.h:226
@ SOF_ISR
Definition: usb.h:217
@ EP3OUT_ISR
Definition: usb.h:229
@ EP7OUT_ISR
Definition: usb.h:237
void usb_init(void)
USB initialization.
Definition: usb.c:520
bool usb_handle_set_feature(void)
Handle SET_FEATURE request.
Definition: usb.c:368