Rev 1661 Rev 1711
1 /******************************************************************** 1 /********************************************************************
2 FileName: usb_descriptors.c 2 FileName: usb_descriptors.c
3 Dependencies: See INCLUDES section 3 Dependencies: See INCLUDES section
4 Processor: PIC18 or PIC24 USB Microcontrollers 4 Processor: PIC18 or PIC24 USB Microcontrollers
5 Hardware: The code is natively intended to be used on the following 5 Hardware: The code is natively intended to be used on the following
6 hardware platforms: PICDEM™ FS USB Demo Board, 6 hardware platforms: PICDEM™ FS USB Demo Board,
7 PIC18F87J50 FS USB Plug-In Module, or 7 PIC18F87J50 FS USB Plug-In Module, or
8 Explorer 16 + PIC24 USB PIM. The firmware may be 8 Explorer 16 + PIC24 USB PIM. The firmware may be
9 modified for use on other USB platforms by editing the 9 modified for use on other USB platforms by editing the
10 HardwareProfile.h file. 10 HardwareProfile.h file.
11 Complier: Microchip C18 (for PIC18) or C30 (for PIC24) 11 Complier: Microchip C18 (for PIC18) or C30 (for PIC24)
12 Company: Microchip Technology, Inc. 12 Company: Microchip Technology, Inc.
13   13  
14 Software License Agreement: 14 Software License Agreement:
15   15  
16 The software supplied herewith by Microchip Technology Incorporated 16 The software supplied herewith by Microchip Technology Incorporated
17 (the “Company”) for its PIC® Microcontroller is intended and 17 (the “Company”) for its PIC® Microcontroller is intended and
18 supplied to you, the Company’s customer, for use solely and 18 supplied to you, the Company’s customer, for use solely and
19 exclusively on Microchip PIC Microcontroller products. The 19 exclusively on Microchip PIC Microcontroller products. The
20 software is owned by the Company and/or its supplier, and is 20 software is owned by the Company and/or its supplier, and is
21 protected under applicable copyright laws. All rights are reserved. 21 protected under applicable copyright laws. All rights are reserved.
22 Any use in violation of the foregoing restrictions may subject the 22 Any use in violation of the foregoing restrictions may subject the
23 user to criminal sanctions under applicable laws, as well as to 23 user to criminal sanctions under applicable laws, as well as to
24 civil liability for the breach of the terms and conditions of this 24 civil liability for the breach of the terms and conditions of this
25 license. 25 license.
26   26  
27 THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES, 27 THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
28 WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED 28 WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
29 TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 29 TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
30 PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, 30 PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
31 IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR 31 IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
32 CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. 32 CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
33   33  
34 ********************************************************************* 34 *********************************************************************
35 -usb_descriptors.c- 35 -usb_descriptors.c-
36 ------------------------------------------------------------------- 36 -------------------------------------------------------------------
37 Filling in the descriptor values in the usb_descriptors.c file: 37 Filling in the descriptor values in the usb_descriptors.c file:
38 ------------------------------------------------------------------- 38 -------------------------------------------------------------------
39   39  
40 [Device Descriptors] 40 [Device Descriptors]
41 The device descriptor is defined as a USB_DEVICE_DESCRIPTOR type. 41 The device descriptor is defined as a USB_DEVICE_DESCRIPTOR type.
42 This type is defined in usb_ch9.h Each entry into this structure 42 This type is defined in usb_ch9.h Each entry into this structure
43 needs to be the correct length for the data type of the entry. 43 needs to be the correct length for the data type of the entry.
44   44  
45 [Configuration Descriptors] 45 [Configuration Descriptors]
46 The configuration descriptor was changed in v2.x from a structure 46 The configuration descriptor was changed in v2.x from a structure
47 to a BYTE array. Given that the configuration is now a byte array 47 to a BYTE array. Given that the configuration is now a byte array
48 each byte of multi-byte fields must be listed individually. This 48 each byte of multi-byte fields must be listed individually. This
49 means that for fields like the total size of the configuration where 49 means that for fields like the total size of the configuration where
50 the field is a 16-bit value "64,0," is the correct entry for a 50 the field is a 16-bit value "64,0," is the correct entry for a
51 configuration that is only 64 bytes long and not "64," which is one 51 configuration that is only 64 bytes long and not "64," which is one
52 too few bytes. 52 too few bytes.
53   53  
54 The configuration attribute must always have the _DEFAULT 54 The configuration attribute must always have the _DEFAULT
55 definition at the minimum. Additional options can be ORed 55 definition at the minimum. Additional options can be ORed
56 to the _DEFAULT attribute. Available options are _SELF and _RWU. 56 to the _DEFAULT attribute. Available options are _SELF and _RWU.
57 These definitions are defined in the usb_device.h file. The 57 These definitions are defined in the usb_device.h file. The
58 _SELF tells the USB host that this device is self-powered. The 58 _SELF tells the USB host that this device is self-powered. The
59 _RWU tells the USB host that this device supports Remote Wakeup. 59 _RWU tells the USB host that this device supports Remote Wakeup.
60   60  
61 [Endpoint Descriptors] 61 [Endpoint Descriptors]
62 Like the configuration descriptor, the endpoint descriptors were 62 Like the configuration descriptor, the endpoint descriptors were
63 changed in v2.x of the stack from a structure to a BYTE array. As 63 changed in v2.x of the stack from a structure to a BYTE array. As
64 endpoint descriptors also has a field that are multi-byte entities, 64 endpoint descriptors also has a field that are multi-byte entities,
65 please be sure to specify both bytes of the field. For example, for 65 please be sure to specify both bytes of the field. For example, for
66 the endpoint size an endpoint that is 64 bytes needs to have the size 66 the endpoint size an endpoint that is 64 bytes needs to have the size
67 defined as "64,0," instead of "64," 67 defined as "64,0," instead of "64,"
68   68  
69 Take the following example: 69 Take the following example:
70 // Endpoint Descriptor // 70 // Endpoint Descriptor //
71 0x07, //the size of this descriptor // 71 0x07, //the size of this descriptor //
72 USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor 72 USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor
73 _EP02_IN, //EndpointAddress 73 _EP02_IN, //EndpointAddress
74 _INT, //Attributes 74 _INT, //Attributes
75 0x08,0x00, //size (note: 2 bytes) 75 0x08,0x00, //size (note: 2 bytes)
76 0x02, //Interval 76 0x02, //Interval
77   77  
78 The first two parameters are self-explanatory. They specify the 78 The first two parameters are self-explanatory. They specify the
79 length of this endpoint descriptor (7) and the descriptor type. 79 length of this endpoint descriptor (7) and the descriptor type.
80 The next parameter identifies the endpoint, the definitions are 80 The next parameter identifies the endpoint, the definitions are
81 defined in usb_device.h and has the following naming 81 defined in usb_device.h and has the following naming
82 convention: 82 convention:
83 _EP<##>_<dir> 83 _EP<##>_<dir>
84 where ## is the endpoint number and dir is the direction of 84 where ## is the endpoint number and dir is the direction of
85 transfer. The dir has the value of either 'OUT' or 'IN'. 85 transfer. The dir has the value of either 'OUT' or 'IN'.
86 The next parameter identifies the type of the endpoint. Available 86 The next parameter identifies the type of the endpoint. Available
87 options are _BULK, _INT, _ISO, and _CTRL. The _CTRL is not 87 options are _BULK, _INT, _ISO, and _CTRL. The _CTRL is not
88 typically used because the default control transfer endpoint is 88 typically used because the default control transfer endpoint is
89 not defined in the USB descriptors. When _ISO option is used, 89 not defined in the USB descriptors. When _ISO option is used,
90 addition options can be ORed to _ISO. Example: 90 addition options can be ORed to _ISO. Example:
91 _ISO|_AD|_FE 91 _ISO|_AD|_FE
92 This describes the endpoint as an isochronous pipe with adaptive 92 This describes the endpoint as an isochronous pipe with adaptive
93 and feedback attributes. See usb_device.h and the USB 93 and feedback attributes. See usb_device.h and the USB
94 specification for details. The next parameter defines the size of 94 specification for details. The next parameter defines the size of
95 the endpoint. The last parameter in the polling interval. 95 the endpoint. The last parameter in the polling interval.
96   96  
97 ------------------------------------------------------------------- 97 -------------------------------------------------------------------
98 Adding a USB String 98 Adding a USB String
99 ------------------------------------------------------------------- 99 -------------------------------------------------------------------
100 A string descriptor array should have the following format: 100 A string descriptor array should have the following format:
101   101  
102 rom struct{byte bLength;byte bDscType;word string[size];}sdxxx={ 102 rom struct{byte bLength;byte bDscType;word string[size];}sdxxx={
103 sizeof(sdxxx),DSC_STR,<text>}; 103 sizeof(sdxxx),DSC_STR,<text>};
104   104  
105 The above structure provides a means for the C compiler to 105 The above structure provides a means for the C compiler to
106 calculate the length of string descriptor sdxxx, where xxx is the 106 calculate the length of string descriptor sdxxx, where xxx is the
107 index number. The first two bytes of the descriptor are descriptor 107 index number. The first two bytes of the descriptor are descriptor
108 length and type. The rest <text> are string texts which must be 108 length and type. The rest <text> are string texts which must be
109 in the unicode format. The unicode format is achieved by declaring 109 in the unicode format. The unicode format is achieved by declaring
110 each character as a word type. The whole text string is declared 110 each character as a word type. The whole text string is declared
111 as a word array with the number of characters equals to <size>. 111 as a word array with the number of characters equals to <size>.
112 <size> has to be manually counted and entered into the array 112 <size> has to be manually counted and entered into the array
113 declaration. Let's study this through an example: 113 declaration. Let's study this through an example:
114 if the string is "USB" , then the string descriptor should be: 114 if the string is "USB" , then the string descriptor should be:
115 (Using index 02) 115 (Using index 02)
116 rom struct{byte bLength;byte bDscType;word string[3];}sd002={ 116 rom struct{byte bLength;byte bDscType;word string[3];}sd002={
117 sizeof(sd002),DSC_STR,'U','S','B'}; 117 sizeof(sd002),DSC_STR,'U','S','B'};
118   118  
119 A USB project may have multiple strings and the firmware supports 119 A USB project may have multiple strings and the firmware supports
120 the management of multiple strings through a look-up table. 120 the management of multiple strings through a look-up table.
121 The look-up table is defined as: 121 The look-up table is defined as:
122 rom const unsigned char *rom USB_SD_Ptr[]={&sd000,&sd001,&sd002}; 122 rom const unsigned char *rom USB_SD_Ptr[]={&sd000,&sd001,&sd002};
123   123  
124 The above declaration has 3 strings, sd000, sd001, and sd002. 124 The above declaration has 3 strings, sd000, sd001, and sd002.
125 Strings can be removed or added. sd000 is a specialized string 125 Strings can be removed or added. sd000 is a specialized string
126 descriptor. It defines the language code, usually this is 126 descriptor. It defines the language code, usually this is
127 US English (0x0409). The index of the string must match the index 127 US English (0x0409). The index of the string must match the index
128 position of the USB_SD_Ptr array, &sd000 must be in position 128 position of the USB_SD_Ptr array, &sd000 must be in position
129 USB_SD_Ptr[0], &sd001 must be in position USB_SD_Ptr[1] and so on. 129 USB_SD_Ptr[0], &sd001 must be in position USB_SD_Ptr[1] and so on.
130 The look-up table USB_SD_Ptr is used by the get string handler 130 The look-up table USB_SD_Ptr is used by the get string handler
131 function. 131 function.
132   132  
133 ------------------------------------------------------------------- 133 -------------------------------------------------------------------
134   134  
135 The look-up table scheme also applies to the configuration 135 The look-up table scheme also applies to the configuration
136 descriptor. A USB device may have multiple configuration 136 descriptor. A USB device may have multiple configuration
137 descriptors, i.e. CFG01, CFG02, etc. To add a configuration 137 descriptors, i.e. CFG01, CFG02, etc. To add a configuration
138 descriptor, user must implement a structure similar to CFG01. 138 descriptor, user must implement a structure similar to CFG01.
139 The next step is to add the configuration descriptor name, i.e. 139 The next step is to add the configuration descriptor name, i.e.
140 cfg01, cfg02,.., to the look-up table USB_CD_Ptr. USB_CD_Ptr[0] 140 cfg01, cfg02,.., to the look-up table USB_CD_Ptr. USB_CD_Ptr[0]
141 is a dummy place holder since configuration 0 is the un-configured 141 is a dummy place holder since configuration 0 is the un-configured
142 state according to the definition in the USB specification. 142 state according to the definition in the USB specification.
143   143  
144 ********************************************************************/ 144 ********************************************************************/
145 145
146 /********************************************************************* 146 /*********************************************************************
147 * Descriptor specific type definitions are defined in: 147 * Descriptor specific type definitions are defined in:
148 * usb_device.h 148 * usb_device.h
149 * 149 *
150 * Configuration options are defined in: 150 * Configuration options are defined in:
151 * usb_config.h 151 * usb_config.h
152 ********************************************************************/ 152 ********************************************************************/
153 #ifndef __USB_DESCRIPTORS_C 153 #ifndef __USB_DESCRIPTORS_C
154 #define __USB_DESCRIPTORS_C 154 #define __USB_DESCRIPTORS_C
155   155  
156 /** INCLUDES *******************************************************/ 156 /** INCLUDES *******************************************************/
157 /* 157 /*
158 #include "GenericTypeDefs.h" 158 #include "GenericTypeDefs.h"
159 #include "Compiler.h" 159 #include "Compiler.h"
160 #include "usb_config.h" 160 #include "usb_config.h"
161 #include "USB/usb_device.h" 161 #include "USB/usb_device.h"
162 */ 162 */
163 #include "./USB/usb.h" 163 #include "./USB/usb.h"
164   164  
165 /** CONSTANTS ******************************************************/ 165 /** CONSTANTS ******************************************************/
166 #if defined(__18CXX) 166 #if defined(__18CXX)
167 #pragma romdata 167 #pragma romdata
168 #endif 168 #endif
169   169  
170 /* Device Descriptor */ 170 /* Device Descriptor */
171 ROM USB_DEVICE_DESCRIPTOR device_dsc= 171 ROM USB_DEVICE_DESCRIPTOR device_dsc=
172 { 172 {
173 0x12, // Size of this descriptor in bytes 173 0x12, // Size of this descriptor in bytes
174 USB_DESCRIPTOR_DEVICE, // DEVICE descriptor type 174 USB_DESCRIPTOR_DEVICE, // DEVICE descriptor type
175 0x0200, // USB Spec Release Number in BCD format 175 0x0200, // USB Spec Release Number in BCD format
176 0x00, // Class Code 176 0x00, // Class Code
177 0x00, // Subclass code 177 0x00, // Subclass code
178 0x00, // Protocol code 178 0x00, // Protocol code
179 USB_EP0_BUFF_SIZE, // Max packet size for EP0, see usb_config.h 179 USB_EP0_BUFF_SIZE, // Max packet size for EP0, see usb_config.h
180 0x16C0, // Vendor ID VOTI AVR USB device 180 0x16C0, // Vendor ID VOTI AVR USB device
181 0x05DC, // Product ID: obdev's free PID 181 0x05DC, // Product ID: obdev's free PID
182 0x0000, // Device release number in BCD format 182 0x0000, // Device release number in BCD format
183 0x01, // Manufacturer string index 183 0x01, // Manufacturer string index
184 0x02, // Product string index 184 0x02, // Product string index
185 0x03, // Device serial number string index 185 0x03, // Device serial number string index
186 0x01 // Number of possible configurations 186 0x01 // Number of possible configurations
187 }; 187 };
188   188  
189 /* Configuration 1 Descriptor */ 189 /* Configuration 1 Descriptor */
190 ROM BYTE configDescriptor1[]={ 190 ROM BYTE configDescriptor1[]={
191 /* Configuration Descriptor */ 191 /* Configuration Descriptor */
192 0x09,//sizeof(USB_CFG_DSC), // Size of this descriptor in bytes 192 0x09,//sizeof(USB_CFG_DSC), // Size of this descriptor in bytes
193 USB_DESCRIPTOR_CONFIGURATION, // CONFIGURATION descriptor type 193 USB_DESCRIPTOR_CONFIGURATION, // CONFIGURATION descriptor type
194 0x20,0x00, // Total length of data for this cfg 194 0x20,0x00, // Total length of data for this cfg
195 1, // Number of interfaces in this cfg 195 1, // Number of interfaces in this cfg
196 1, // Index value of this configuration 196 1, // Index value of this configuration
197 0, // Configuration string index 197 0, // Configuration string index
198 _DEFAULT | _SELF, // Attributes, see usb_device.h 198 _DEFAULT | _SELF, // Attributes, see usb_device.h
199 50, // Max power consumption (2X mA) 199 50, // Max power consumption (2X mA)
200 200
201 /* Interface Descriptor */ 201 /* Interface Descriptor */
202 0x09,//sizeof(USB_INTF_DSC), // Size of this descriptor in bytes 202 0x09,//sizeof(USB_INTF_DSC), // Size of this descriptor in bytes
203 USB_DESCRIPTOR_INTERFACE, // INTERFACE descriptor type 203 USB_DESCRIPTOR_INTERFACE, // INTERFACE descriptor type
204 0, // Interface Number 204 0, // Interface Number
205 0, // Alternate Setting Number 205 0, // Alternate Setting Number
206 2, // Number of endpoints in this intf 206 2, // Number of endpoints in this intf
207 0x00, // Class code 207 0x00, // Class code
208 0x00, // Subclass code 208 0x00, // Subclass code
209 0x00, // Protocol code 209 0x00, // Protocol code
210 0, // Interface string index 210 0, // Interface string index
211 211
212 /* Endpoint Descriptor */ 212 /* Endpoint Descriptor */
213 0x07, /*sizeof(USB_EP_DSC)*/ 213 0x07, /*sizeof(USB_EP_DSC)*/
214 USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor 214 USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor
215 _EP01_OUT, //EndpointAddress 215 _EP01_OUT, //EndpointAddress
216 _BULK, //Attributes 216 _BULK, //Attributes
217 USBGEN_EP_SIZE,0x00, //size 217 USBGEN_EP_SIZE,0x00, //size
218 1, //Interval 218 1, //Interval
219 219
220 0x07, /*sizeof(USB_EP_DSC)*/ 220 0x07, /*sizeof(USB_EP_DSC)*/
221 USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor 221 USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor
222 _EP01_IN, //EndpointAddress 222 _EP01_IN, //EndpointAddress
223 _BULK, //Attributes 223 _BULK, //Attributes
224 USBGEN_EP_SIZE,0x00, //size 224 USBGEN_EP_SIZE,0x00, //size
225 1 //Interval 225 1 //Interval
226 }; 226 };
227   227  
228   228  
229 //Language code string descriptor 229 //Language code string descriptor
230 ROM struct{BYTE bLength;BYTE bDscType;WORD string[1];}sd000={ 230 ROM struct{BYTE bLength;BYTE bDscType;WORD string[1];}sd000={
231 sizeof(sd000),USB_DESCRIPTOR_STRING,{0x0409}}; 231 sizeof(sd000),USB_DESCRIPTOR_STRING,{0x0409}};
232   232  
233 //Manufacturer string descriptor 233 //Manufacturer string descriptor
234 ROM struct{BYTE bLength;BYTE bDscType;WORD string[12];}sd001={ 234 ROM struct{BYTE bLength;BYTE bDscType;WORD string[12];}sd001={
235 sizeof(sd001),USB_DESCRIPTOR_STRING, 235 sizeof(sd001),USB_DESCRIPTOR_STRING,
236 {'w','w','w','.','o','b','d','e','v','.', 236 {'w','w','w','.','o','b','d','e','v','.',
237 'a','t'}}; 237 'a','t'}};
238   238  
239 //Product string descriptor 239 //Product string descriptor
240 ROM struct{BYTE bLength;BYTE bDscType;WORD string[10];}sd002={ 240 ROM struct{BYTE bLength;BYTE bDscType;WORD string[10];}sd002={
241 sizeof(sd002),USB_DESCRIPTOR_STRING, 241 sizeof(sd002),USB_DESCRIPTOR_STRING,
242 {'D','G','8','S','A','Q','-','I','2','C'}}; 242 {'D','G','8','S','A','Q','-','I','2','C'}};
243   243  
244 //Serial Number string descriptor 244 //Serial Number string descriptor
245 ROM struct{BYTE bLength;BYTE bDscType;WORD string[9];}sd003={ 245 ROM struct{BYTE bLength;BYTE bDscType;WORD string[9];}sd003={
246 sizeof(sd003),USB_DESCRIPTOR_STRING, 246 sizeof(sd003),USB_DESCRIPTOR_STRING,
247 {'T','F','3','L','J','-','1','.','0'}}; 247 {'T','F','3','L','J','-','1','.','0'}};
248   248  
249 //Array of configuration descriptors 249 //Array of configuration descriptors
250 ROM BYTE *ROM USB_CD_Ptr[]= 250 ROM BYTE *ROM USB_CD_Ptr[]=
251 { 251 {
252 (ROM BYTE *ROM)&configDescriptor1 252 (ROM BYTE *ROM)&configDescriptor1
253 }; 253 };
254 //Array of string descriptors 254 //Array of string descriptors
255 ROM BYTE *ROM USB_SD_Ptr[]= 255 ROM BYTE *ROM USB_SD_Ptr[]=
256 { 256 {
257 (ROM BYTE *ROM)&sd000, 257 (ROM BYTE *ROM)&sd000,
258 (ROM BYTE *ROM)&sd001, 258 (ROM BYTE *ROM)&sd001,
259 (ROM BYTE *ROM)&sd002, 259 (ROM BYTE *ROM)&sd002,
260 (ROM BYTE *ROM)&sd003 260 (ROM BYTE *ROM)&sd003
261 }; 261 };
262   262  
263 /** EOF usb_descriptors.c ***************************************************/ 263 /** EOF usb_descriptors.c ***************************************************/
264   264  
265 #endif 265 #endif