FreeCalypso > hg > freecalypso-hwlab

comparison doc/USB-IDs @ 166:ef1b8b6c4aee

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/USB-IDs: new paradigm
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 31 Jul 2023 00:00:13 +0000
parents bac08ce19c08
children df4bf4e06221
comparison
equal deleted inserted replaced
165:7a4e8d23ab3a 166:ef1b8b6c4aee
1 USB PIDs 0x7150 through 0x7157 out of FTDI's VID 0x0403 have been officially 1 USB PIDs 0x7150 through 0x7157 out of FTDI's VID 0x0403 have been officially
2 allocated by FTDI to Falconia Partners LLC for use in our company's hardware 2 allocated by FTDI to Falconia Partners LLC for use in our company's hardware
3 products based on FTDI chips. The sole authority for further assignment and 3 products based on FTDI chips. The sole authority for further assignment and
4 use of these USB IDs rests with Mychaela N. Falconia and no one else. The 4 use of these USB IDs rests with Mychaela N. Falconia and no one else.
5 following assignments have been made so far: 5
6 6 Falconia-made vs off-the-shelf hardware
7 0403:7150 FreeCalypso UART+JTAG adapter (hw dev currently paused) 7 =======================================
8 0403:7151 given to community for FT2232D-based unbuffered JTAG adapters 8
9 0403:7152 FreeCalypso DUART28C adapter (with boot control outputs) 9 The common-sense ethical rules imposed by FTDI on the use of USB PIDs allocated
10 0403:7153 not assigned yet 10 out of their VID 0x0403 stipulate that these USB IDs may be assigned only to
11 0403:7154 not assigned yet 11 board-level products that use FTDI chips. However, in the case of USB PIDs
12 0403:7155 not assigned yet 12 allocated by FTDI to Falconia Partners LLC, there is no specific requirement
13 0403:7156 not assigned yet 13 that all board-level products using these ID codes must be physically
14 0403:7157 reserved for lab use (not for shipping products) 14 manufactured by our company: we can also program these ID codes into FTDI chip
15 EEPROMs on various off-the-shelf boards made by parties other than us, as long
16 as (1) those off-the-shelf boards feature genuine FTDI-made chips and (2) we as
17 in Falconia Partners LLC retain full control and sole deciding authority as to
18 which boards we program these ID codes into, when and how.
19
20 As of 2023-07, we have only one board-level product with an FTDI chip that was
21 physically manufactured by us: our FreeCalypso DUART28 adapter, produced in
22 year 2020. That board has two supported EEPROM configurations, switchable by
23 end users, one of which uses an FTDI-Falconia USB ID code. Aside from this
24 Falconia-made DUART28, we've been programming FTDI-Falconia USB ID codes into
25 some off-the-shelf boards with FTDI chips:
26
27 * In earlier years we made heavy use of generic FT2232D breakout boards made by
28 PLDkit OU in Estonia. We are not sure if that original company still makes
29 them or not, but the person behind that company name did eventually sell us
30 their Gerber files, and we have published them here:
31
32 ftp://ftp.freecalypso.org/pub/USB/FTDI/
33
34 Given that we have a stash of FT2232D chips and given that we still have use
35 cases for these generic breakout boards, we have a tentative plan to produce
36 our own Falconia-branded version of the same adapter/breakout board.
37
38 * We are now starting to play with iCE40 FPGA designs using a Lattice iCEstick
39 board, and we quickly discovered that instead of programming their FT2232H
40 EEPROM with a distinguishing VID:PID code, Lattice left that EEPROM blank.
41 To fix the problem of Linux kernel creating a bogus ttyUSB device for FT2232H
42 Channel A which subsequently disappears when the developer-operator runs
43 iceprog, we program the EEPROM ourselves, using one of our FTDI-Falconia PIDs
44 that is recognized by mainline Linux (since 2020-09) as a "JTAG quirk" device,
45 binding a ttyUSB device only to Channel B.
46
47 Specific hw product vs particular desired treatment from Linux kernel
48 =====================================================================
49
50 The original intent being USB VID:PID codes was to assign a different ID code
51 to each different physical hardware product. However, when it comes to
52 assigning different USB ID codes to various FTDI-based boards where the actual
53 chip always stays the same, there is only one reason to program any custom ID
54 codes at all: to elicit special treatment from the ftdi_sio driver in the Linux
55 kernel. If the EEPROM is omitted, left blank or programmed with the chip-
56 default VID:PID code, the ftdi_sio driver will bind a ttyUSB device to every
57 channel of a multichannel FT2232x or FT4232H chip; the only reason why anyone
58 would wish to program a non-standard USB ID code and (in all cases but one) go
59 through the pain of getting that code added to Linux is if this default ftdi_sio
60 driver behaviour is undesirable and some different special handling is desired
61 or required:
62
63 * Some FTDI-based designs support non-UART functions only and should be ignored
64 altogether by the ftdi_sio driver. In these cases, program a USB ID code
65 that is not known at all to this Linux kernel driver.
66
67 * In many designs FT2232x Channel A is used for MPSSE (JTAG or SPI), while
68 Channel B is used as a UART. In this case the desire is to tell the ftdi_sio
69 driver to bind a ttyUSB device only to Channel B, and there is an ever-growing
70 list of USB ID codes (typically one or more from each board maker who ran into
71 this issue) that are recognized by the ftdi_sio driver as "JTAG quirk"
72 devices.
73
74 * In yet other cases some other special quirk other than "skip Channel A for
75 JTAG" is desired from the ftdi_sio driver. We have one such use case in
76 FreeCalypso: we have dual-UART configurations (FT2232x chip, both channels
77 used as UARTs and need ttyUSB devices) in which the ttyUSB device for
78 Channel A needs to be fully standard, but the one for Channel B is modified
79 with a special quirk - see our Linux-DTR-RTS-flaw article.
80
81 Specific FTDI-Falconia PID assignments
82 ======================================
83
84 Our original plan was to assign specific ID codes out of our allocated range to
85 specific hw products of our own design and make, following the classic model
86 for USB VID:PID assignments. However, upon gaining some years of real-life
87 experience, we have switched to a Linux-centric model: we assign USB ID codes
88 based not on what physical hw it is, but on what kind of special treatment we
89 seek from the ftdi_sio driver in Linux.
90
91 Furthermore and in an unconventional stance, we (Falconia family, doing business
92 as Falconia Partners LLC) explicitly allow any member of FOSS & OSHW community,
93 without any need to communicate with us, to program some of our FTDI-Falconia
94 USB PIDs into their own FTDI-based boards, under one essential condition - any
95 non-Falconia party who wishes to use one of our FTDI-Falconia USB PIDs may do
96 so if and only if:
97
98 * The specific PID code you wish to reuse is explicitly listed in the present
99 document as being eligible for third-party reuse;
100
101 * The manner in which you use that PID code is exactly as prescribed in this
102 document, not any other way.
103
104 VID 0x0403, PIDs 0x7150 and 0x7151
105 ==================================
106
107 USB ID codes 0403:7150 and 0403:7151 are recognized by the ftdi_sio driver in
108 mainline Linux (since 2020-09) as "JTAG quirk" devices: the driver binds only
109 to Channel B and creates only one ttyUSB device. We (Falconia) grant permission
110 to anyone in FOSS & OSHW community to reuse either of these two ID codes in
111 their own FTDI-based board designs, or in their own personal programming of ID
112 EEPROMs on off-the-shelf FTDI-based boards, provided that:
113
114 * The FTDI chip is either FT2232C/D/L or FT2232H, genuine FTDI;
115
116 * Your intent with respect to handling from the ftdi_sio driver in Linux (or
117 its equivalent in other operating systems) is the same as ours: create a
118 ttyUSB device for Channel B only, while Channel A remains unbound.
119
120 Choice between 0x7150 and 0x7151
121 --------------------------------
122
123 Our original intent was to use PID 0x7150 for a planned buffered JTAG adapter
124 which we ended up never actually making, while 0x7151 was allocated for
125 programming into generic FT2232D breakout boards for an unbuffered JTAG adapter
126 configuration. As of 2023-07, that previously planned distinction is now
127 officially revoked: both PIDs may be used for any FTDI-based board-level gadget
128 that needs "JTAG quirk" handling from the ftdi_sio driver.
129
130 When to comes to our own (Falconia/FreeCalypso) usage, our current plan as of
131 2023-07 is to use PID 0x7150 for FPGA boards that use FT2232x Channel A for
132 FPGA configuration and/or FPGA SPI flash programming, and use PID 0x7151 for
133 all JTAG adapters, buffered or unbuffered. However, other FOSS & OSHW community
134 members may use either PID, as long as the requirements listed above are met.
135
136 USB ID 0x0403:0x7152
137 ====================
138
139 For this FTDI-Falconia PID *NO* outside use permission is currently granted: we
140 as in Falconia family, doing business as Falconia Partners LLC, reserve this
141 FTDI-allocated PID for use in our own products only. We use this USB ID on
142 multiple hardware products, all of which meet the following criteria:
143
144 * The FTDI chip is two-channel FT2232x;
145
146 * Both channels are wired as UARTs and actually used as such, thus needing two
147 ttyUSB devices in Linux;
148
149 * Channel A is a fully standard UART, no special quirks;
150
151 * The ttyUSB device for Channel B must be given a special quirk: automatic
152 assertion of DTR & RTS upon device open MUST be suppressed, while TIOCMBIS
153 and TIOCMBIC ioctls remain available for explicit user control of these two
154 signals.
155
156 The original user of this USB ID code is the 'C' configuration of our DUART28
157 hardware adapter (thus forming DUART28C); our current plan is to reuse the same
158 wiring arrangement and the same USB ID code on our upcoming FC Venus board.
159
160 USB ID 0x0403:0x7153
161 ====================
162
163 This USB ID code is explicitly reserved for community use - specifically, for
164 anyone who needs the same suppression of DTR & RTS auto-assertion which we've
165 implemented for 0x0403:0x7152, but needs it on a single-channel FTDI device, or
166 on all channels of a multichannel FTDI chip. We (Falconia) grant permission to
167 anyone in FOSS & OSHW community to use this USB ID code in their own FTDI-based
168 board designs, or in their own personal programming of ID EEPROMs on off-the-
169 shelf FTDI-based boards, provided that:
170
171 * The chip is genuine FTDI;
172
173 * Your intent with respect to handling from the ftdi_sio driver in Linux (or
174 its equivalent in other operating systems) is the same as ours: intentionally
175 make this particular ttyUSB device non-POSIX-compliant by NOT automatically
176 raising DTR and RTS on open, instead leaving all control over these two
177 signals up to userspace via explicit TIOCMBIS and TIOCMBIC ioctls.
178
179 VID 0x0403, PIDs 0x7154 through 0x7156
180 ======================================
181
182 These 3 FTDI-Falconia PIDs are currently unassigned. NO permission is granted
183 to any outside parties to use any of these unassigned PIDs.
184
185 USB ID 0x0403:0x7157
186 ====================
187
188 This USB ID code is reserved for FTDI-based board-level gadgets that are
189 entirely non-UART and should be skipped altogether by the ftdi_sio driver.
190 Examples include, but are not limited to single-channel FT232H used for JTAG or
191 other MPSSE applications, FT2232H with both channels wired for MPSSE, or FT2232x
192 in MCU host bus emulation mode. We (Falconia) grant permission to anyone in
193 FOSS & OSHW community to use this USB ID code in their own FTDI-based board
194 designs, or in their own personal programming of ID EEPROMs on off-the-shelf
195 FTDI-based boards, provided that:
196
197 * The chip is genuine FTDI;
198
199 * Your intent with respect to handling from the ftdi_sio driver in Linux (or
200 its equivalent in other operating systems) is the same as ours: have the
201 driver ignore this FTDI-based USB device altogether and NOT bind to it.
202
203 Textual ID strings
204 ==================
205
206 The configuration EEPROM on FTDI chips (internal on FT232R, external on most
207 others) allows the higher-level integrator to set not only VID:PID codes, but
208 also textual ID strings for manufacturer and product. We (Falconia/FreeCalypso)
209 always set meaningful textual ID strings in all of our FTDI EEPROM programming,
210 and we encourage others to do likewise. Furthermore, because we have switched
211 to using VID:PID codes to indicate what handling we seek from the ftdi_sio
212 driver in the Linux kernel, as opposed to identifying more specific hw products
213 or designs, it is no longer possible to locate specific device types by looking
214 at VID:PID alone. For this reason, our new philosophy is that userspace
215 applications that need to locate a specific type of non-UART FTDI device should
216 match not only by VID:PID, but also by looking for specific product ID strings.