FreeCalypso > hg > fc-usbser-tools
comparison doc/FTDI-EEPROM-format @ 71:0b37be8b23ca
doc/FTDI-EEPROM-format: document string descriptors
| author | Mychaela Falconia <falcon@freecalypso.org> |
|---|---|
| date | Sun, 24 Sep 2023 22:27:38 +0000 |
| parents | 09da7db45dce |
| children | 6dc3aa777fd6 |
comparison
equal
deleted
inserted
replaced
| 70:09da7db45dce | 71:0b37be8b23ca |
|---|---|
| 146 This byte has the same bit assignments across all FTDI chips we work with, | 146 This byte has the same bit assignments across all FTDI chips we work with, |
| 147 although newer chips don't support some of the older bits: | 147 although newer chips don't support some of the older bits: |
| 148 | 148 |
| 149 bit 0: isochronous endpoint control on FT232BM and FT2232C/D | 149 bit 0: isochronous endpoint control on FT232BM and FT2232C/D |
| 150 bit 1: isochronous endpoint control on FT232BM and FT2232C/D | 150 bit 1: isochronous endpoint control on FT232BM and FT2232C/D |
| 151 Bit 2: enable suspend mode pull-down on I/O pins (all chips) | 151 bit 2: enable suspend mode pull-down on I/O pins (all chips) |
| 152 bit 3: 1 means serial number string present, 0 means serial # string absent | 152 bit 3: 1 means serial number string present, 0 means serial # string absent |
| 153 bit 4: set bcdUSB in device descriptor to EEPROM value (only up to FT2232C/D) | 153 bit 4: set bcdUSB in device descriptor to EEPROM value (only up to FT2232C/D) |
| 154 bit 5: isochronous endpoint control on FT2232C/D | 154 bit 5: isochronous endpoint control on FT2232C/D |
| 155 bit 6: isochronous endpoint control on FT2232C/D | 155 bit 6: isochronous endpoint control on FT2232C/D |
| 156 | 156 |
| 267 | 267 |
| 268 Please refer to libftdi source for the codes that go into individual 4-bit | 268 Please refer to libftdi source for the codes that go into individual 4-bit |
| 269 fields for each CBUSx. | 269 fields for each CBUSx. |
| 270 | 270 |
| 271 The strings area of the EEPROM begins with word 12 or byte offset 0x18. | 271 The strings area of the EEPROM begins with word 12 or byte offset 0x18. |
| 272 | |
| 273 USB string descriptors | |
| 274 ====================== | |
| 275 | |
| 276 The standard USB device descriptor returned by FTDI chips has iManufacturer set | |
| 277 to 1 and iProduct set to 2, indicating presence of string descriptors at these | |
| 278 indices. If byte 0A bit 3 is set, iSerialNumber is set to 3, otherwise | |
| 279 iSerialNumber is set to 0, indicating absence of serial number string. | |
| 280 | |
| 281 The string descriptors themselves, returned upon the host asking for them at | |
| 282 these indices, are stored verbatim in the strings area of the EEPROM, i.e., in | |
| 283 the free space following the fixed configuration structure for each chip. | |
| 284 | |
| 285 As defined in the USB spec, each string descriptor has the following structure: | |
| 286 | |
| 287 1 byte: total number of bytes in the descriptor | |
| 288 1 byte: constant 0x03, meaning string descriptor | |
| 289 variable bytes: string body in UCS-2 | |
| 290 | |
| 291 The total number of bytes in a string descriptor is the number of UCS-2 | |
| 292 characters times 2 plus 2; this number is written into the first byte of the | |
| 293 descriptor itself, in the least-significant half of the first 16-bit word. The | |
| 294 whole descriptor, consisting of this header word followed by UCS-2 character | |
| 295 words, can be placed at any EEPROM location that isn't taken or reserved for | |
| 296 something else, and there is a pointer to each of the 3 possible string | |
| 297 descriptors from the fixed header structure at the beginning of the EEPROM. | |
| 298 | |
| 299 Each of the 3 string pointers is one 16-bit word, structured as follows: | |
| 300 | |
| 301 lower byte: EEPROM byte address where the descriptor starts | |
| 302 upper byte: total number of bytes in the descriptor, same as written | |
| 303 in the descriptor itself | |
| 304 | |
| 305 String placement quirk | |
| 306 ---------------------- | |
| 307 | |
| 308 It should be apparent from the above description that each string descriptor | |
| 309 can be placed anywhere in the EEPROM, as long as that location doesn't clash | |
| 310 with something else. The most natural way is to put the manufacturer ID string | |
| 311 right after the fixed config structure, then the product ID string and then the | |
| 312 serial number string, if included - but FTDI's official tools *almost* follow | |
| 313 this principle, with two quirks: | |
| 314 | |
| 315 * In the case of 93C56 or 93C66 EEPROMs, FTDI's official tools skip 64 words | |
| 316 (128 bytes) after the end of the chip-defined config structure and then place | |
| 317 the manufacturer ID string after this gap. The byte-address pointer to each | |
| 318 string descriptor always has its high bit set as a result of this quirk. | |
| 319 | |
| 320 * In the case of 1024-bit EEPROMs (93C46 or FT232R internal) nothing is skipped, | |
| 321 but the byte-address pointers to strings are written with the high bit set, | |
| 322 as if the EEPROM were of 93C56 type. | |
| 323 | |
| 324 Our current ftee-gen* tools replicate these quirks, as they are essentially | |
| 325 harmless. The only downside of this design is that one cannot use a 93C56 | |
| 326 EEPROM to include longer strings - but designing a product with unnaturally | |
| 327 long ID strings, so long that FTDI's official tools won't support them, seems | |
| 328 like a bad idea. |