-
Notifications
You must be signed in to change notification settings - Fork 3
/
usb_descriptors.c
323 lines (282 loc) · 15.6 KB
/
usb_descriptors.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
/********************************************************************
FileName: usb_descriptors.c
Dependencies: See INCLUDES section
Processor: PIC16, PIC18, PIC24, or dsPIC USB Microcontrollers
Complier: Microchip XC8 (for PIC16/PIC18), C18 (for PIC18)
or XC16 (for PIC24/dsPIC33 devices)
Company: Microchip Technology, Inc.
Software License Agreement:
The software supplied herewith by Microchip Technology Incorporated
(the "Company") for its PIC(R) Microcontroller is intended and
supplied to you, the Company's customer, for use solely and
exclusively on Microchip PIC Microcontroller products. The
software is owned by the Company and/or its supplier, and is
protected under applicable copyright laws. All rights are reserved.
Any use in violation of the foregoing restrictions may subject the
user to criminal sanctions under applicable laws, as well as to
civil liability for the breach of the terms and conditions of this
license.
THIS SOFTWARE IS PROVIDED IN AN "AS IS" CONDITION. NO WARRANTIES,
WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
*********************************************************************
-usb_descriptors.c-
-------------------------------------------------------------------
Filling in the descriptor values in the usb_descriptors.c file:
-------------------------------------------------------------------
[Device Descriptors]
The device descriptor is defined as a USB_DEVICE_DESCRIPTOR type.
This type is defined in usb_ch9.h Each entry into this structure
needs to be the correct length for the data type of the entry.
[Configuration Descriptors]
The configuration descriptor was changed in v2.x from a structure
to a uint8_t array. Given that the configuration is now a byte array
each byte of multi-byte fields must be listed individually. This
means that for fields like the total size of the configuration where
the field is a 16-bit value "64,0," is the correct entry for a
configuration that is only 64 bytes long and not "64," which is one
too few bytes.
The configuration attribute must always have the _DEFAULT
definition at the minimum. Additional options can be ORed
to the _DEFAULT attribute. Available options are _SELF and _RWU.
These definitions are defined in the usb_device.h file. The
_SELF tells the USB host that this device is self-powered. The
_RWU tells the USB host that this device supports Remote Wakeup.
[Endpoint Descriptors]
Like the configuration descriptor, the endpoint descriptors were
changed in v2.x of the stack from a structure to a uint8_t array. As
endpoint descriptors also has a field that are multi-byte entities,
please be sure to specify both bytes of the field. For example, for
the endpoint size an endpoint that is 64 bytes needs to have the size
defined as "64,0," instead of "64,"
Take the following example:
// Endpoint Descriptor //
0x07, //the size of this descriptor //
USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor
_EP02_IN, //EndpointAddress
_INT, //Attributes
0x08,0x00, //size (note: 2 bytes)
0x02, //Interval
The first two parameters are self-explanatory. They specify the
length of this endpoint descriptor (7) and the descriptor type.
The next parameter identifies the endpoint, the definitions are
defined in usb_device.h and has the following naming
convention:
_EP<##>_<dir>
where ## is the endpoint number and dir is the direction of
transfer. The dir has the value of either 'OUT' or 'IN'.
The next parameter identifies the type of the endpoint. Available
options are _BULK, _INT, _ISO, and _CTRL. The _CTRL is not
typically used because the default control transfer endpoint is
not defined in the USB descriptors. When _ISO option is used,
addition options can be ORed to _ISO. Example:
_ISO|_AD|_FE
This describes the endpoint as an isochronous pipe with adaptive
and feedback attributes. See usb_device.h and the USB
specification for details. The next parameter defines the size of
the endpoint. The last parameter in the polling interval.
-------------------------------------------------------------------
Adding a USB String
-------------------------------------------------------------------
A string descriptor array should have the following format:
rom struct{byte bLength;byte bDscType;word string[size];}sdxxx={
sizeof(sdxxx),DSC_STR,<text>};
The above structure provides a means for the C compiler to
calculate the length of string descriptor sdxxx, where xxx is the
index number. The first two bytes of the descriptor are descriptor
length and type. The rest <text> are string texts which must be
in the unicode format. The unicode format is achieved by declaring
each character as a word type. The whole text string is declared
as a word array with the number of characters equals to <size>.
<size> has to be manually counted and entered into the array
declaration. Let's study this through an example:
if the string is "USB" , then the string descriptor should be:
(Using index 02)
rom struct{byte bLength;byte bDscType;word string[3];}sd002={
sizeof(sd002),DSC_STR,'U','S','B'};
A USB project may have multiple strings and the firmware supports
the management of multiple strings through a look-up table.
The look-up table is defined as:
rom const unsigned char *rom USB_SD_Ptr[]={&sd000,&sd001,&sd002};
The above declaration has 3 strings, sd000, sd001, and sd002.
Strings can be removed or added. sd000 is a specialized string
descriptor. It defines the language code, usually this is
US English (0x0409). The index of the string must match the index
position of the USB_SD_Ptr array, &sd000 must be in position
USB_SD_Ptr[0], &sd001 must be in position USB_SD_Ptr[1] and so on.
The look-up table USB_SD_Ptr is used by the get string handler
function.
-------------------------------------------------------------------
The look-up table scheme also applies to the configuration
descriptor. A USB device may have multiple configuration
descriptors, i.e. CFG01, CFG02, etc. To add a configuration
descriptor, user must implement a structure similar to CFG01.
The next step is to add the configuration descriptor name, i.e.
cfg01, cfg02,.., to the look-up table USB_CD_Ptr. USB_CD_Ptr[0]
is a dummy place holder since configuration 0 is the un-configured
state according to the definition in the USB specification.
********************************************************************/
/*********************************************************************
* Descriptor specific type definitions are defined in:
* usb_device.h
*
* Configuration options are defined in:
* usb_config.h
********************************************************************/
#ifndef __USB_DESCRIPTORS_C
#define __USB_DESCRIPTORS_C
/** INCLUDES *******************************************************/
#include "usb.h"
/** CONSTANTS ******************************************************/
#if defined(COMPILER_MPLAB_C18)
#pragma romdata
#endif
/* Device Descriptor */
const USB_DEVICE_DESCRIPTOR device_dsc=
{
0x12, //Size of this descriptor in bytes
USB_DESCRIPTOR_DEVICE, //DEVICE descriptor type
0x0200, //USB Spec Release Number in BCD format
0x00, //Class Code
0x00, //Subclass code
0x00, //Protocol code
USB_EP0_BUFF_SIZE, //Max packet size for EP0, see usb_config.h
0x04D8, //Vendor ID: Microchip Technology, Inc.
0xF4CD, //Product ID: 28Cxxx EEPROM Programmer
0x0100, //Device release number in BCD format
0x01, //Manufacturer string index
0x02, //Product string index
0x00, //Device serial number string index
0x01 //Number of possible configurations
};
/* Configuration 1 Descriptor */
const uint8_t configDescriptor1[]={
/* Configuration Descriptor */
0x09, //Size of this descriptor in bytes
USB_DESCRIPTOR_CONFIGURATION, //CONFIGURATION descriptor type
0x20,0x00, //Total length of data for this cfg
1, //Number of interfaces in this cfg
1, //Index value of this configuration
0, //Configuration string index
_DEFAULT, //Attributes, see usb_device.h
50, //Max power consumption (2X mA)
/* Interface Descriptor */
0x09, //Size of this descriptor in bytes
USB_DESCRIPTOR_INTERFACE, //INTERFACE descriptor type
0, //Interface Number
0, //Alternate Setting Number
2, //Number of endpoints in this intf
0xFF, //Class code
0xFF, //Subclass code
0xFF, //Protocol code
0, //Interface string index
/* Endpoint Descriptor */
0x07, //Size of this descriptor in bytes
USB_DESCRIPTOR_ENDPOINT,//Endpoint Descriptor
_EP01_OUT, //EndpointAddress
_BULK, //Attributes
USBGEN_EP_SIZE,0x00, //Size
1, //Interval
0x07, //Size of this descriptor in bytes
USB_DESCRIPTOR_ENDPOINT,//Endpoint Descriptor
_EP01_IN, //EndpointAddress
_BULK, //Attributes
USBGEN_EP_SIZE,0x00, //Size
1 //Interval
};
//Language code string descriptor
const struct{uint8_t bLength;uint8_t bDscType;uint16_t string[1];}sd000={
sizeof(sd000),USB_DESCRIPTOR_STRING,{0x0409}};
//Manufacturer string descriptor
const struct{uint8_t bLength;uint8_t bDscType;uint16_t string[15];}sd001={
sizeof(sd001),USB_DESCRIPTOR_STRING,
{'S','t','e','v','e','n',' ','S','t','a','l','l','i','o','n'}};
//Product string descriptor
const struct{uint8_t bLength;uint8_t bDscType;uint16_t string[24];}sd002={
sizeof(sd002),USB_DESCRIPTOR_STRING,
{'2','8','C','x','x','x',' ','E','E','P','R','O','M',' ','P','r','o','g','r','a','m','m','e','r'}};
//Serial number string descriptor. If a serial number string is implemented,
//it should be unique for every single device coming off the production assembly
//line. Plugging two devices with the same serial number into a computer
//simultaneously will cause problems (in extreme cases BSOD).
//Note: Common OSes put restrictions on the possible values that are allowed.
//For best OS compatibility, the serial number string should only consist
//of UNICODE encoded numbers 0 through 9 and capital letters A through F.
//ROM struct{BYTE bLength;BYTE bDscType;WORD string[10];}sd003={
//sizeof(sd003),USB_DESCRIPTOR_STRING,
//{'0','1','2','3','4','5','6','7','8','9'}};
//Array of configuration descriptors
const uint8_t *const USB_CD_Ptr[]=
{
(const uint8_t *const)&configDescriptor1
};
//Array of string descriptors
const uint8_t *const USB_SD_Ptr[]=
{
(const uint8_t *const)&sd000,
(const uint8_t *const)&sd001,
(const uint8_t *const)&sd002
//(const uint8_t *const)&sd003 //uncomment if implementing a serial number string descriptor named sd003
};
#if defined(IMPLEMENT_MICROSOFT_OS_DESCRIPTOR)
//Microsoft "OS Descriptor" - This descriptor is based on a Microsoft specific
//specification (not part of the standard USB 2.0 specs or class specs).
//Implementing this special descriptor allows WinUSB driver package installation
//to be automatic on Windows 8. For additional details, see:
//http://msdn.microsoft.com/en-us/library/windows/hardware/hh450799(v=vs.85).aspx
const MS_OS_DESCRIPTOR MSOSDescriptor =
{
sizeof(MSOSDescriptor), //bLength - lenght of this descriptor in bytes
USB_DESCRIPTOR_STRING, //bDescriptorType - "string"
{'M','S','F','T','1','0','0'}, //qwSignature - special values that specifies the OS descriptor spec version that this firmware implements
GET_MS_DESCRIPTOR, //bMS_VendorCode - defines the "GET_MS_DESCRIPTOR" bRequest literal value
0x00 //bPad - always 0x00
};
//Extended Compat ID OS Feature Descriptor
const MS_COMPAT_ID_FEATURE_DESC CompatIDFeatureDescriptor =
{
//----------Header Section--------------
sizeof(CompatIDFeatureDescriptor), //dwLength
0x0100, //bcdVersion = 1.00
EXTENDED_COMPAT_ID, //wIndex
0x01, //bCount - 0x01 "Function Section(s)" implemented in this descriptor
{0,0,0,0,0,0,0}, //Reserved[7]
//----------Function Section 1----------
0x00, //bFirstInterfaceNumber: the WinUSB interface in this firmware is interface #0
0x01, //Reserved - fill this reserved byte with 0x01 according to documentation
{'W','I','N','U','S','B',0x00,0x00},//compatID - "WINUSB" (with two null terminators to fill all 8 bytes)
{0,0,0,0,0,0,0,0}, //subCompatID - eight bytes of 0
{0,0,0,0,0,0} //Reserved
};
//Extended Properties OS Feature Descriptor
const MS_EXT_PROPERTY_FEATURE_DESC ExtPropertyFeatureDescriptor =
{
//----------Header Section--------------
sizeof(ExtPropertyFeatureDescriptor), //dwLength
0x0100, //bcdVersion = 1.00
EXTENDED_PROPERTIES, //wIndex
0x0001, //wCount - 0x0001 "Property Sections" implemented in this descriptor
//----------Property Section 1----------
132, //dwSize - 132 bytes in this Property Section
0x00000001, //dwPropertyDataType (Unicode string)
40, //wPropertyNameLength - 40 bytes in the bPropertyName field
{'D','e','v','i','c','e','I','n','t','e','r','f','a','c','e','G','U','I','D', 0x0000}, //bPropertyName - "DeviceInterfaceGUID"
78, //dwPropertyDataLength - 78 bytes in the bPropertyData field (GUID value in UNICODE formatted string, with braces and dashes)
//The below value is the Device Interface GUID (a 128-bit long "globally unique identifier")
//Please modify the GUID value in your application before moving to production.
//When you change the GUID, you must also change the PC application software
//that connects to this device, as the software looks for the device based on
//VID, PID, and GUID. All three values in the PC application must match
//the values in this firmware.
//The GUID value can be a randomly generated 128-bit hexadecimal number,
//formatted like the below value. The actual value is not important,
//so long as it is almost certain to be globally unique, and matches the
//PC software that communicates with this firmware.
{'{','a','8','3','8','0','1','b','2','-','7','b','6','a','-','4','d','5','1','-','8','a','0','2','-','8','a','e','5','f','2','a','d','3','2','2','c','}',0x0000} //bPropertyData - this is the actual GUID value. Make sure this matches the PC application code trying to connect to the device.
};
#endif
/** EOF usb_descriptors.c ***************************************************/
#endif