00001 /******************************************************************** 00002 FileName: usb_descriptors.c 00003 Dependencies: See INCLUDES section 00004 Processor: PIC18 or PIC24 USB Microcontrollers 00005 Hardware: The code is natively intended to be used on the following 00006 hardware platforms: PICDEM FS USB Demo Board, 00007 PIC18F87J50 FS USB Plug-In Module, or 00008 Explorer 16 + PIC24 USB PIM. The firmware may be 00009 modified for use on other USB platforms by editing the 00010 HardwareProfile.h file. 00011 Complier: Microchip C18 (for PIC18) or C30 (for PIC24) 00012 Company: Microchip Technology, Inc. 00013 00014 Software License Agreement: 00015 00016 The software supplied herewith by Microchip Technology Incorporated 00017 (the Company) for its PICŽ Microcontroller is intended and 00018 supplied to you, the Companys customer, for use solely and 00019 exclusively on Microchip PIC Microcontroller products. The 00020 software is owned by the Company and/or its supplier, and is 00021 protected under applicable copyright laws. All rights are reserved. 00022 Any use in violation of the foregoing restrictions may subject the 00023 user to criminal sanctions under applicable laws, as well as to 00024 civil liability for the breach of the terms and conditions of this 00025 license. 00026 00027 THIS SOFTWARE IS PROVIDED IN AN AS IS CONDITION. NO WARRANTIES, 00028 WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED 00029 TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 00030 PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, 00031 IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR 00032 CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. 00033 00034 ********************************************************************* 00035 -usb_descriptors.c- 00036 ------------------------------------------------------------------- 00037 Filling in the descriptor values in the usb_descriptors.c file: 00038 ------------------------------------------------------------------- 00039 00040 [Device Descriptors] 00041 The device descriptor is defined as a USB_DEVICE_DESCRIPTOR type. 00042 This type is defined in usb_ch9.h Each entry into this structure 00043 needs to be the correct length for the data type of the entry. 00044 00045 [Configuration Descriptors] 00046 The configuration descriptor was changed in v2.x from a structure 00047 to a BYTE array. Given that the configuration is now a byte array 00048 each byte of multi-byte fields must be listed individually. This 00049 means that for fields like the total size of the configuration where 00050 the field is a 16-bit value "64,0," is the correct entry for a 00051 configuration that is only 64 bytes long and not "64," which is one 00052 too few bytes. 00053 00054 The configuration attribute must always have the _DEFAULT 00055 definition at the minimum. Additional options can be ORed 00056 to the _DEFAULT attribute. Available options are _SELF and _RWU. 00057 These definitions are defined in the usb_device.h file. The 00058 _SELF tells the USB host that this device is self-powered. The 00059 _RWU tells the USB host that this device supports Remote Wakeup. 00060 00061 [Endpoint Descriptors] 00062 Like the configuration descriptor, the endpoint descriptors were 00063 changed in v2.x of the stack from a structure to a BYTE array. As 00064 endpoint descriptors also has a field that are multi-byte entities, 00065 please be sure to specify both bytes of the field. For example, for 00066 the endpoint size an endpoint that is 64 bytes needs to have the size 00067 defined as "64,0," instead of "64," 00068 00069 Take the following example: 00070 // Endpoint Descriptor // 00071 0x07, //the size of this descriptor // 00072 USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor 00073 _EP02_IN, //EndpointAddress 00074 _INT, //Attributes 00075 0x08,0x00, //size (note: 2 bytes) 00076 0x02, //Interval 00077 00078 The first two parameters are self-explanatory. They specify the 00079 length of this endpoint descriptor (7) and the descriptor type. 00080 The next parameter identifies the endpoint, the definitions are 00081 defined in usb_device.h and has the following naming 00082 convention: 00083 _EP<##>_<dir> 00084 where ## is the endpoint number and dir is the direction of 00085 transfer. The dir has the value of either 'OUT' or 'IN'. 00086 The next parameter identifies the type of the endpoint. Available 00087 options are _BULK, _INT, _ISO, and _CTRL. The _CTRL is not 00088 typically used because the default control transfer endpoint is 00089 not defined in the USB descriptors. When _ISO option is used, 00090 addition options can be ORed to _ISO. Example: 00091 _ISO|_AD|_FE 00092 This describes the endpoint as an isochronous pipe with adaptive 00093 and feedback attributes. See usb_device.h and the USB 00094 specification for details. The next parameter defines the size of 00095 the endpoint. The last parameter in the polling interval. 00096 00097 ------------------------------------------------------------------- 00098 Adding a USB String 00099 ------------------------------------------------------------------- 00100 A string descriptor array should have the following format: 00101 00102 rom struct{byte bLength;byte bDscType;word string[size];}sdxxx={ 00103 sizeof(sdxxx),DSC_STR,<text>}; 00104 00105 The above structure provides a means for the C compiler to 00106 calculate the length of string descriptor sdxxx, where xxx is the 00107 index number. The first two bytes of the descriptor are descriptor 00108 length and type. The rest <text> are string texts which must be 00109 in the unicode format. The unicode format is achieved by declaring 00110 each character as a word type. The whole text string is declared 00111 as a word array with the number of characters equals to <size>. 00112 <size> has to be manually counted and entered into the array 00113 declaration. Let's study this through an example: 00114 if the string is "USB" , then the string descriptor should be: 00115 (Using index 02) 00116 rom struct{byte bLength;byte bDscType;word string[3];}sd002={ 00117 sizeof(sd002),DSC_STR,'U','S','B'}; 00118 00119 A USB project may have multiple strings and the firmware supports 00120 the management of multiple strings through a look-up table. 00121 The look-up table is defined as: 00122 rom const unsigned char *rom USB_SD_Ptr[]={&sd000,&sd001,&sd002}; 00123 00124 The above declaration has 3 strings, sd000, sd001, and sd002. 00125 Strings can be removed or added. sd000 is a specialized string 00126 descriptor. It defines the language code, usually this is 00127 US English (0x0409). The index of the string must match the index 00128 position of the USB_SD_Ptr array, &sd000 must be in position 00129 USB_SD_Ptr[0], &sd001 must be in position USB_SD_Ptr[1] and so on. 00130 The look-up table USB_SD_Ptr is used by the get string handler 00131 function. 00132 00133 ------------------------------------------------------------------- 00134 00135 The look-up table scheme also applies to the configuration 00136 descriptor. A USB device may have multiple configuration 00137 descriptors, i.e. CFG01, CFG02, etc. To add a configuration 00138 descriptor, user must implement a structure similar to CFG01. 00139 The next step is to add the configuration descriptor name, i.e. 00140 cfg01, cfg02,.., to the look-up table USB_CD_Ptr. USB_CD_Ptr[0] 00141 is a dummy place holder since configuration 0 is the un-configured 00142 state according to the definition in the USB specification. 00143 00144 ********************************************************************/ 00145 00146 /********************************************************************* 00147 * Descriptor specific type definitions are defined in: 00148 * usb_device.h 00149 * 00150 * Configuration options are defined in: 00151 * usb_config.h 00152 ********************************************************************/ 00153 #ifndef __USB_DESCRIPTORS_C 00154 #define __USB_DESCRIPTORS_C 00155 00157 #include "GenericTypeDefs.h" 00158 #include "Compiler.h" 00159 #include "usb_config.h" 00160 #include "./USB/usb.h" 00161 #include "./USB/usb_function_cdc.h" 00162 00164 #if defined(__18CXX) 00165 #pragma romdata 00166 #endif 00167 00168 /* Device Descriptor */ 00169 ROM USB_DEVICE_DESCRIPTOR device_dsc= 00170 { 00171 0x12, // Size of this descriptor in bytes 00172 USB_DESCRIPTOR_DEVICE, // DEVICE descriptor type 00173 0x0200, // USB Spec Release Number in BCD format 00174 CDC_DEVICE, // Class Code 00175 0x00, // Subclass code 00176 0x00, // Protocol code 00177 USB_EP0_BUFF_SIZE, // Max packet size for EP0, see usb_config.h 00178 0x4D8, // Vendor ID 00179 0x000A, // Product ID: CDC RS-232 Emulation Demo 00180 0x0001, // Device release number in BCD format 00181 0x01, // Manufacturer string index 00182 0x02, // Product string index 00183 0x00, // Device serial number string index 00184 0x01 // Number of possible configurations 00185 }; 00186 00187 /* Configuration 1 Descriptor */ 00188 ROM BYTE configDescriptor1[]= 00189 { 00190 /* Configuration Descriptor */ 00191 0x09,//sizeof(USB_CFG_DSC), // Size of this descriptor in bytes 00192 USB_DESCRIPTOR_CONFIGURATION, // CONFIGURATION descriptor type 00193 67,0, // Total length of data for this cfg 00194 2, // Number of interfaces in this cfg 00195 1, // Index value of this configuration 00196 0, // Configuration string index 00197 _DEFAULT | _SELF, // Attributes, see usb_device.h 00198 50, // Max power consumption (2X mA) 00199 00200 /* Interface Descriptor */ 00201 9,//sizeof(USB_INTF_DSC), // Size of this descriptor in bytes 00202 USB_DESCRIPTOR_INTERFACE, // INTERFACE descriptor type 00203 0, // Interface Number 00204 0, // Alternate Setting Number 00205 1, // Number of endpoints in this intf 00206 COMM_INTF, // Class code 00207 ABSTRACT_CONTROL_MODEL, // Subclass code 00208 V25TER, // Protocol code 00209 0, // Interface string index 00210 00211 /* CDC Class-Specific Descriptors */ 00212 sizeof(USB_CDC_HEADER_FN_DSC), 00213 CS_INTERFACE, 00214 DSC_FN_HEADER, 00215 0x10,0x01, 00216 00217 sizeof(USB_CDC_ACM_FN_DSC), 00218 CS_INTERFACE, 00219 DSC_FN_ACM, 00220 USB_CDC_ACM_FN_DSC_VAL, 00221 00222 sizeof(USB_CDC_UNION_FN_DSC), 00223 CS_INTERFACE, 00224 DSC_FN_UNION, 00225 CDC_COMM_INTF_ID, 00226 CDC_DATA_INTF_ID, 00227 00228 sizeof(USB_CDC_CALL_MGT_FN_DSC), 00229 CS_INTERFACE, 00230 DSC_FN_CALL_MGT, 00231 0x00, 00232 CDC_DATA_INTF_ID, 00233 00234 /* Endpoint Descriptor */ 00235 //sizeof(USB_EP_DSC),DSC_EP,_EP02_IN,_INT,CDC_INT_EP_SIZE,0x02, 00236 0x07,/*sizeof(USB_EP_DSC)*/ 00237 USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor 00238 _EP02_IN, //EndpointAddress 00239 _INTERRUPT, //Attributes 00240 0x08,0x00, //size 00241 0x02, //Interval 00242 00243 /* Interface Descriptor */ 00244 9,//sizeof(USB_INTF_DSC), // Size of this descriptor in bytes 00245 USB_DESCRIPTOR_INTERFACE, // INTERFACE descriptor type 00246 1, // Interface Number 00247 0, // Alternate Setting Number 00248 2, // Number of endpoints in this intf 00249 DATA_INTF, // Class code 00250 0, // Subclass code 00251 NO_PROTOCOL, // Protocol code 00252 0, // Interface string index 00253 00254 /* Endpoint Descriptor */ 00255 //sizeof(USB_EP_DSC),DSC_EP,_EP03_OUT,_BULK,CDC_BULK_OUT_EP_SIZE,0x00, 00256 0x07,/*sizeof(USB_EP_DSC)*/ 00257 USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor 00258 _EP03_OUT, //EndpointAddress 00259 _BULK, //Attributes 00260 0x40,0x00, //size 00261 0x00, //Interval 00262 00263 /* Endpoint Descriptor */ 00264 //sizeof(USB_EP_DSC),DSC_EP,_EP03_IN,_BULK,CDC_BULK_IN_EP_SIZE,0x00 00265 0x07,/*sizeof(USB_EP_DSC)*/ 00266 USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor 00267 _EP03_IN, //EndpointAddress 00268 _BULK, //Attributes 00269 0x40,0x00, //size 00270 0x00, //Interval 00271 }; 00272 00273 00274 //Language code string descriptor 00275 ROM struct 00276 { 00277 BYTE bLength; 00278 BYTE bDscType; 00279 WORD string[1]; 00280 }sd000= 00281 { 00282 sizeof(sd000),USB_DESCRIPTOR_STRING,{0x0409} 00283 }; 00284 00285 //Manufacturer string descriptor 00286 ROM struct 00287 { 00288 BYTE bLength; 00289 BYTE bDscType; 00290 WORD string[25]; 00291 }sd001= 00292 { 00293 sizeof(sd001),USB_DESCRIPTOR_STRING, 00294 {'M','i','c','r','o','c','h','i','p',' ', 00295 'T','e','c','h','n','o','l','o','g','y',' ','I','n','c','.' 00296 } 00297 }; 00298 00299 //Product string descriptor 00300 ROM struct 00301 { 00302 BYTE bLength; 00303 BYTE bDscType; 00304 WORD string[25]; 00305 }sd002= 00306 { 00307 sizeof(sd002),USB_DESCRIPTOR_STRING, 00308 {'C','D','C',' ','R','S','-','2','3','2',' ', 00309 'E','m','u','l','a','t','i','o','n',' ','D','e','m','o'} 00310 }; 00311 00312 //Array of configuration descriptors 00313 ROM BYTE *ROM USB_CD_Ptr[]= 00314 { 00315 (ROM BYTE *ROM)&configDescriptor1 00316 }; 00317 //Array of string descriptors 00318 ROM BYTE *ROM USB_SD_Ptr[USB_NUM_STRING_DESCRIPTORS]= 00319 { 00320 (ROM BYTE *ROM)&sd000, 00321 (ROM BYTE *ROM)&sd001, 00322 (ROM BYTE *ROM)&sd002 00323 }; 00324 00325 #pragma code 00326 #endif 00327