--- a/doc/USB-IDs	Sun Jul 30 18:10:51 2023 +0000
+++ b/doc/USB-IDs	Mon Jul 31 00:00:13 2023 +0000
@@ -1,14 +1,216 @@
 USB PIDs 0x7150 through 0x7157 out of FTDI's VID 0x0403 have been officially
 allocated by FTDI to Falconia Partners LLC for use in our company's hardware
 products based on FTDI chips.  The sole authority for further assignment and
-use of these USB IDs rests with Mychaela N. Falconia and no one else.  The
-following assignments have been made so far:
+use of these USB IDs rests with Mychaela N. Falconia and no one else.
+
+Falconia-made vs off-the-shelf hardware
+=======================================
+
+The common-sense ethical rules imposed by FTDI on the use of USB PIDs allocated
+out of their VID 0x0403 stipulate that these USB IDs may be assigned only to
+board-level products that use FTDI chips.  However, in the case of USB PIDs
+allocated by FTDI to Falconia Partners LLC, there is no specific requirement
+that all board-level products using these ID codes must be physically
+manufactured by our company: we can also program these ID codes into FTDI chip
+EEPROMs on various off-the-shelf boards made by parties other than us, as long
+as (1) those off-the-shelf boards feature genuine FTDI-made chips and (2) we as
+in Falconia Partners LLC retain full control and sole deciding authority as to
+which boards we program these ID codes into, when and how.
+
+As of 2023-07, we have only one board-level product with an FTDI chip that was
+physically manufactured by us: our FreeCalypso DUART28 adapter, produced in
+year 2020.  That board has two supported EEPROM configurations, switchable by
+end users, one of which uses an FTDI-Falconia USB ID code.  Aside from this
+Falconia-made DUART28, we've been programming FTDI-Falconia USB ID codes into
+some off-the-shelf boards with FTDI chips:
+
+* In earlier years we made heavy use of generic FT2232D breakout boards made by
+  PLDkit OU in Estonia.  We are not sure if that original company still makes
+  them or not, but the person behind that company name did eventually sell us
+  their Gerber files, and we have published them here:
+
+  ftp://ftp.freecalypso.org/pub/USB/FTDI/
+
+  Given that we have a stash of FT2232D chips and given that we still have use
+  cases for these generic breakout boards, we have a tentative plan to produce
+  our own Falconia-branded version of the same adapter/breakout board.
+
+* We are now starting to play with iCE40 FPGA designs using a Lattice iCEstick
+  board, and we quickly discovered that instead of programming their FT2232H
+  EEPROM with a distinguishing VID:PID code, Lattice left that EEPROM blank.
+  To fix the problem of Linux kernel creating a bogus ttyUSB device for FT2232H
+  Channel A which subsequently disappears when the developer-operator runs
+  iceprog, we program the EEPROM ourselves, using one of our FTDI-Falconia PIDs
+  that is recognized by mainline Linux (since 2020-09) as a "JTAG quirk" device,
+  binding a ttyUSB device only to Channel B.
+
+Specific hw product vs particular desired treatment from Linux kernel
+=====================================================================
+
+The original intent being USB VID:PID codes was to assign a different ID code
+to each different physical hardware product.  However, when it comes to
+assigning different USB ID codes to various FTDI-based boards where the actual
+chip always stays the same, there is only one reason to program any custom ID
+codes at all: to elicit special treatment from the ftdi_sio driver in the Linux
+kernel.  If the EEPROM is omitted, left blank or programmed with the chip-
+default VID:PID code, the ftdi_sio driver will bind a ttyUSB device to every
+channel of a multichannel FT2232x or FT4232H chip; the only reason why anyone
+would wish to program a non-standard USB ID code and (in all cases but one) go
+through the pain of getting that code added to Linux is if this default ftdi_sio
+driver behaviour is undesirable and some different special handling is desired
+or required:
+
+* Some FTDI-based designs support non-UART functions only and should be ignored
+  altogether by the ftdi_sio driver.  In these cases, program a USB ID code
+  that is not known at all to this Linux kernel driver.
+
+* In many designs FT2232x Channel A is used for MPSSE (JTAG or SPI), while
+  Channel B is used as a UART.  In this case the desire is to tell the ftdi_sio
+  driver to bind a ttyUSB device only to Channel B, and there is an ever-growing
+  list of USB ID codes (typically one or more from each board maker who ran into
+  this issue) that are recognized by the ftdi_sio driver as "JTAG quirk"
+  devices.
+
+* In yet other cases some other special quirk other than "skip Channel A for
+  JTAG" is desired from the ftdi_sio driver.  We have one such use case in
+  FreeCalypso: we have dual-UART configurations (FT2232x chip, both channels
+  used as UARTs and need ttyUSB devices) in which the ttyUSB device for
+  Channel A needs to be fully standard, but the one for Channel B is modified
+  with a special quirk - see our Linux-DTR-RTS-flaw article.
+
+Specific FTDI-Falconia PID assignments
+======================================
+
+Our original plan was to assign specific ID codes out of our allocated range to
+specific hw products of our own design and make, following the classic model
+for USB VID:PID assignments.  However, upon gaining some years of real-life
+experience, we have switched to a Linux-centric model: we assign USB ID codes
+based not on what physical hw it is, but on what kind of special treatment we
+seek from the ftdi_sio driver in Linux.
+
+Furthermore and in an unconventional stance, we (Falconia family, doing business
+as Falconia Partners LLC) explicitly allow any member of FOSS & OSHW community,
+without any need to communicate with us, to program some of our FTDI-Falconia
+USB PIDs into their own FTDI-based boards, under one essential condition - any
+non-Falconia party who wishes to use one of our FTDI-Falconia USB PIDs may do
+so if and only if:
+
+* The specific PID code you wish to reuse is explicitly listed in the present
+  document as being eligible for third-party reuse;
+
+* The manner in which you use that PID code is exactly as prescribed in this
+  document, not any other way.
+
+VID 0x0403, PIDs 0x7150 and 0x7151
+==================================
 
-0403:7150	FreeCalypso UART+JTAG adapter (hw dev currently paused)
-0403:7151	given to community for FT2232D-based unbuffered JTAG adapters
-0403:7152	FreeCalypso DUART28C adapter (with boot control outputs)
-0403:7153	not assigned yet
-0403:7154	not assigned yet
-0403:7155	not assigned yet
-0403:7156	not assigned yet
-0403:7157	reserved for lab use (not for shipping products)
+USB ID codes 0403:7150 and 0403:7151 are recognized by the ftdi_sio driver in
+mainline Linux (since 2020-09) as "JTAG quirk" devices: the driver binds only
+to Channel B and creates only one ttyUSB device.  We (Falconia) grant permission
+to anyone in FOSS & OSHW community to reuse either of these two ID codes in
+their own FTDI-based board designs, or in their own personal programming of ID
+EEPROMs on off-the-shelf FTDI-based boards, provided that:
+
+* The FTDI chip is either FT2232C/D/L or FT2232H, genuine FTDI;
+
+* Your intent with respect to handling from the ftdi_sio driver in Linux (or
+  its equivalent in other operating systems) is the same as ours: create a
+  ttyUSB device for Channel B only, while Channel A remains unbound.
+
+Choice between 0x7150 and 0x7151
+--------------------------------
+
+Our original intent was to use PID 0x7150 for a planned buffered JTAG adapter
+which we ended up never actually making, while 0x7151 was allocated for
+programming into generic FT2232D breakout boards for an unbuffered JTAG adapter
+configuration.  As of 2023-07, that previously planned distinction is now
+officially revoked: both PIDs may be used for any FTDI-based board-level gadget
+that needs "JTAG quirk" handling from the ftdi_sio driver.
+
+When to comes to our own (Falconia/FreeCalypso) usage, our current plan as of
+2023-07 is to use PID 0x7150 for FPGA boards that use FT2232x Channel A for
+FPGA configuration and/or FPGA SPI flash programming, and use PID 0x7151 for
+all JTAG adapters, buffered or unbuffered.  However, other FOSS & OSHW community
+members may use either PID, as long as the requirements listed above are met.
+
+USB ID 0x0403:0x7152
+====================
+
+For this FTDI-Falconia PID *NO* outside use permission is currently granted: we
+as in Falconia family, doing business as Falconia Partners LLC, reserve this
+FTDI-allocated PID for use in our own products only.  We use this USB ID on
+multiple hardware products, all of which meet the following criteria:
+
+* The FTDI chip is two-channel FT2232x;
+
+* Both channels are wired as UARTs and actually used as such, thus needing two
+  ttyUSB devices in Linux;
+
+* Channel A is a fully standard UART, no special quirks;
+
+* The ttyUSB device for Channel B must be given a special quirk: automatic
+  assertion of DTR & RTS upon device open MUST be suppressed, while TIOCMBIS
+  and TIOCMBIC ioctls remain available for explicit user control of these two
+  signals.
+
+The original user of this USB ID code is the 'C' configuration of our DUART28
+hardware adapter (thus forming DUART28C); our current plan is to reuse the same
+wiring arrangement and the same USB ID code on our upcoming FC Venus board.
+
+USB ID 0x0403:0x7153
+====================
+
+This USB ID code is explicitly reserved for community use - specifically, for
+anyone who needs the same suppression of DTR & RTS auto-assertion which we've
+implemented for 0x0403:0x7152, but needs it on a single-channel FTDI device, or
+on all channels of a multichannel FTDI chip.  We (Falconia) grant permission to
+anyone in FOSS & OSHW community to use this USB ID code in their own FTDI-based
+board designs, or in their own personal programming of ID EEPROMs on off-the-
+shelf FTDI-based boards, provided that:
+
+* The chip is genuine FTDI;
+
+* Your intent with respect to handling from the ftdi_sio driver in Linux (or
+  its equivalent in other operating systems) is the same as ours: intentionally
+  make this particular ttyUSB device non-POSIX-compliant by NOT automatically
+  raising DTR and RTS on open, instead leaving all control over these two
+  signals up to userspace via explicit TIOCMBIS and TIOCMBIC ioctls.
+
+VID 0x0403, PIDs 0x7154 through 0x7156
+======================================
+
+These 3 FTDI-Falconia PIDs are currently unassigned.  NO permission is granted
+to any outside parties to use any of these unassigned PIDs.
+
+USB ID 0x0403:0x7157
+====================
+
+This USB ID code is reserved for FTDI-based board-level gadgets that are
+entirely non-UART and should be skipped altogether by the ftdi_sio driver.
+Examples include, but are not limited to single-channel FT232H used for JTAG or
+other MPSSE applications, FT2232H with both channels wired for MPSSE, or FT2232x
+in MCU host bus emulation mode.  We (Falconia) grant permission to anyone in
+FOSS & OSHW community to use this USB ID code in their own FTDI-based board
+designs, or in their own personal programming of ID EEPROMs on off-the-shelf
+FTDI-based boards, provided that:
+
+* The chip is genuine FTDI;
+
+* Your intent with respect to handling from the ftdi_sio driver in Linux (or
+  its equivalent in other operating systems) is the same as ours: have the
+  driver ignore this FTDI-based USB device altogether and NOT bind to it.
+
+Textual ID strings
+==================
+
+The configuration EEPROM on FTDI chips (internal on FT232R, external on most
+others) allows the higher-level integrator to set not only VID:PID codes, but
+also textual ID strings for manufacturer and product.  We (Falconia/FreeCalypso)
+always set meaningful textual ID strings in all of our FTDI EEPROM programming,
+and we encourage others to do likewise.  Furthermore, because we have switched
+to using VID:PID codes to indicate what handling we seek from the ftdi_sio
+driver in the Linux kernel, as opposed to identifying more specific hw products
+or designs, it is no longer possible to locate specific device types by looking
+at VID:PID alone.  For this reason, our new philosophy is that userspace
+applications that need to locate a specific type of non-UART FTDI device should
+match not only by VID:PID, but also by looking for specific product ID strings.