--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/FTDI-chip-ID	Wed Sep 13 00:43:14 2023 +0000
@@ -0,0 +1,41 @@
+Q: How do various standard software components (ftdi_sio driver in the Linux
+   kernel, libftdi etc) identify what kind of FTDI chip they are talking to?
+   For example, how do they tell apart between FT2232C/D and FT2232H with their
+   respective differences in features and capabilities?
+
+A: They look primarily at the bcdDevice word in the USB device descriptor.  One
+   can also look at bNumInterfaces in the configuration descriptor (more
+   reliable, as will be seen momentarily) to distinguish between single-channel
+   vs dual-channel vs 4-channel devices, but bcdDevice is still the only way to
+   tell apart between FT232BM and FT232R, or between FT2232C/D and FT2232H.
+
+However, this all-important bcdDevice word exhibits a very noteworthy quirk: it
+is included in FTDI's EEPROM configuration structure, thus it can be overridden
+through EEPROM programming.  The result is that at least on some FTDI chips (so
+far I've only tested this quirk on FT2232D) one can make the chip report a
+different bcdDevice code than its true chip version, and thus fool standard
+host software!  Needless to say, doing so is a very bad idea: the actual
+behavior of the chip, the way it acts upon various bits in the EEPROM config
+structure and the way it reacts to various USB commands, does not change just
+because you changed the "device release number" code, thus various host control
+functions will start misbehaving and failing in mysterious ways.
+
+Our FTDI EEPROM tools (see FTDI-EEPROM-tools article) often need to know what
+kind of FTDI chip you are working with as in reading, programming or preparing
+an EEPROM image for.  Most competitor tools (for example, the ones integrated
+into libftdi) do the same thing as all other standard host software components:
+they look at the reported bcdDevice and use this code to decide what kind of
+FTDI chip they are working with - hence they will be misled and broken if this
+word is misprogrammed in an EEPROM.  To avoid this issue, our FTDI EEPROM tools
+follow a different design: with our tools you as the operator are responsible
+for knowing what kind of FTDI chip you are working with - our tools do NOT
+attempt to autodetect the chip, as it is impossible to do so in an environment
+that may include badly corrupted or misprogrammed EEPROMs.  Specifically, you
+are responsible for manually selecting the correct generator tool (for example,
+ftee-gen2232c vs ftee-gen2232h in the case FT2232x) and manually specifying
+your EEPROM size with -b or -B options if you are working with a board design
+that uses a 93C56 or 93C66 EEPROM.
+
+This largely-manual design of our FTDI EEPROM tools makes them less friendly to
+casual users, but in return they should be able to recover from any possible
+EEPROM corruption or misprogramming, accidental or malicious.