# HG changeset patch # User Mychaela Falconia # Date 1694413925 0 # Node ID 49be28a15768d1454ad2ba6e9db14e3deaaa94ec # Parent 916488f7a8e083253832431546cdf875efe73550 USB-ID-assignments: new official document location Our master document for assignment of USB IDs that have been allocated to us by FTDI previously resided in doc/USB-IDs in freecalypso-hwlab repository. However, that hw lab hacks repository is not the right place for a long-term official policy document - the present repository is a much better place. diff -r 916488f7a8e0 -r 49be28a15768 USB-ID-assignments --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/USB-ID-assignments Mon Sep 11 06:32:05 2023 +0000 @@ -0,0 +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. + +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 +================================== + +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.