# HG changeset patch # User Mychaela Falconia # Date 1694415065 0 # Node ID df4bf4e06221e33b7f09d9434df4027af57b3722 # Parent e75478dda3040cd0624f5841698924ef4a14b34b doc: several articles moved to other repositories diff -r e75478dda304 -r df4bf4e06221 doc/DUART28-EEPROM-config --- a/doc/DUART28-EEPROM-config Mon Sep 11 05:24:26 2023 +0000 +++ b/doc/DUART28-EEPROM-config Mon Sep 11 06:51:05 2023 +0000 @@ -1,70 +1,3 @@ -The EEPROM on the DUART28 adapter board has two valid configurations: DUART28C -and DUART28S. As of this writing the S configuration is the default shipping -one, but this situation may change in the future. The difference between the -two configs is in the USB VID:PID presented by the USB device, and this USB ID -difference has the following practical impact: - -* The C configuration presents a custom USB ID and requires a custom patch to - the Linux kernel ftdi_sio driver in order to work - without this ftdi_sio - driver patch it won't work at all. But if you do go through the pain of - applying the needed patch to your Linux kernel ftdi_sio driver, the reward - is that you get not only the two Calypso UARTs, but also working boot control - outputs. - -* The S configuration presents the default FT2232x USB ID and is therefore - supported out of the box by the standard Linux ftdi_sio driver without needing - any patches. However, the adapter's CTL1 and CTL2 outputs cannot be used in - this configuration (they will be bogusly asserted whenever Channel B ttyUSB - device is opened), and thus they must be left unconnected, and you don't get - to play with the remote boot control feature. - -The physical hardware is identical between the two configurations, only the -EEPROM programming changes, thus end users need to be able to switch freely -between the two EEPROM configs as they wish. This article explains how to -program the EEPROM back and forth between the two configs. - -Determining your current DUART28 config -======================================= - -Connect the USB cable between your DUART28 board and your Linux host, and -observe dmesg output. If your DUART28 board is in the C configuration, it will -present as USB ID 0403:7152, and if it is in the S config, it will present as -USB ID 0403:6010. You can also see these USB IDs with lsusb. The product ID -string is also programmed as "DUART28C" or "DUART28S". +This article has moved; the new location is: -Converting from DUART28S to DUART28C -==================================== - -If your DUART28 board is currently in the S config, its USB ID will be -0403:6010, which is the default ID for FTDI's two-channel FT2232x family. -Because it is the standard default, there are plenty of other gadgets using the -same ID - thus you need to ensure that you have no other USB devices with the -same ID connected to your system during the reprogramming operation. Run lsusb -and ensure that you see only one USB device with ID 0403:6010. Ensure that this -one device really is your DUART28 board: unplug that USB cable and make sure -that the device disappears, plug it back in and make sure that it reappears. - -One you have confirmed that you won't inadvertently hit some other FT2232x -device, execute the actual programming command as follows (from the top -directory of this code repository): - -ftee-gen2232c eeproms/duart28c $Serial | fteeprom-prog i:0x0403:0x6010 - -(See FTDI-EEPROM-tools article for other ways to specify the target device to - fteeprom-prog.) - -Replace the $Serial metavariable with the 3-digit serial number of your DUART28 -adapter board as it appears on the factory serial number sticker. - -After this operation completes successfully, unplug and replug the USB cable -between the DUART28 board and your host - the adapter should now show up with -USB ID 0403:7152. - -Converting from DUART28C to DUART28S -==================================== - -If your DUART28 board is currently in the C config, its USB ID will be -0403:7152, which is a private ID that belongs to us and should not be used by -other parties. The reverse conversion command is as follows: - -ftee-gen2232c eeproms/duart28s $Serial | fteeprom-prog i:0x0403:0x7152 +https://www.freecalypso.org/hg/fc-usbser-tools/file/tip/doc/DUART28-EEPROM-config diff -r e75478dda304 -r df4bf4e06221 doc/FT232R-notes --- a/doc/FT232R-notes Mon Sep 11 05:24:26 2023 +0000 +++ b/doc/FT232R-notes Mon Sep 11 06:51:05 2023 +0000 @@ -1,42 +1,3 @@ -Unlike FT2232x devices with external EEPROMs, an FT232R device is not expected -to ever have a blank EEPROM in normal usage: these chips have their EEPROM -built in, and FTDI probably ships them with this internal EEPROM already -programmed. I said "probably" because I have not yet had an occasion to build -my own FT232R-containing board where I would be getting completely pristine -"bare" chips from Digi-Key, thus I have no first-hand verified knowledge. - -As an experiment, I have programmed "blank" (0xFFFF in every word) images into -the two FT232R devices I have available for play at the moment (specifically -devices which I could afford to brick if things went badly), and FT232R behaves -the same way as FTDI's earlier chips with external EEPROMs: it runs with a fixed -default config when the EEPROM is invalid. But this configuration is NOT -recommended for production use - you should always have a valid EEPROM config -in your FT232R chip. +This article has moved; the new location is: -When our FreeCalypso fteeprom tools were first put together in 2019-04, I was -getting erratic behaviour: when I tried to program my own EEPROM config -generated with ftee-gen232r, the resulting EEPROM content became a bitwise AND -between the previous image and the new one, as if the "EEPROM" is not really an -erasable memory, but one of OTP kind where ones can be turned into zeros, but -not the other way around. I was doing this experiment on a no-name FT232RL -adapter from ebay, thus my first thought was that the FT232RL chip was bad, a -less-than-perfect clone rather than genuine FTDI. But then I bought a UB232R -module from Digi-Key (presumably containing a genuine FT232RQ chip), and it -behaved the same way. - -Further investigation revealed that FT232R EEPROM write operations work -correctly only if they are preceded by this magic sequence: - - ftdi_usb_reset(&ftdi); - ftdi_poll_modem_status(&ftdi, &modem_status); - ftdi_set_latency_timer(&ftdi, 0x77); - -I can see how FTDI could have reasonably implemented a sort of safety lock on -their EEPROM write operations, allowing them only if a special unlock sequence -has been given - but it completely baffles me why they are doing some sort of -OTP emulation in the absence of the right magic sequence, as opposed to -disabling EEPROM writes altogether. It is worth noting that this magic sequence -is NOT needed for programming external EEPROMs behind FT2232x chips - were FTDI -folks being deliberately malicious in designing their FT232R chip to simulate -appearance of being bricked when it is programmed with older (or third-party) -software tools that don't know the new magic sequence? Who knows... +https://www.freecalypso.org/hg/fc-usbser-tools/file/tip/doc/FT232R-notes diff -r e75478dda304 -r df4bf4e06221 doc/FTDI-EEPROM-tools --- a/doc/FTDI-EEPROM-tools Mon Sep 11 05:24:26 2023 +0000 +++ b/doc/FTDI-EEPROM-tools Mon Sep 11 06:51:05 2023 +0000 @@ -1,243 +1,3 @@ -Mother Mychaela has developed a set of Linux command line tools for manipulating -configuration EEPROMs that are attached to FT2232x devices and accessed in-band -via USB. This document describes these tools. - -Supported FTDI chips and EEPROMs -================================ - -The present tools work with 93C46, 93C56 and 93C66 EEPROMs attached behind -FT2232x dual-channel UART/FIFO/MPSSE/etc chips, both FT2232C/D and FT2232H. -We can read these EEPROMs for examination or backup, and we can program them -with new bits, either restoring a previously saved backup or creating a new -from-scratch configuration. These EEPROM configurations (which we can save, -restore or create from scratch) set the USB VID:PID and the textual strings -naming the manufacturer, the product model and an optional serial number, -select whether each FT2232x channel will come up in the default UART mode or -one of the other EEPROM-configurable modes (245 FIFO, CPU-style FIFO or fast -opto-isolated serial), and allow a few other obscure chip settings to be -tweaked. - -Some work has also been done toward the goal of being able to program the -internal EEPROM in FT232R chips (a very popular single-channel USB to UART -converter needing no external components), but this work should be considered -experimental: the tools appear to work on an UB232R module from Digi-Key -(presumably containing a genuine FT232RQ chip) and on a no-name FT232RL adapter -where the chip is uncertain, but because we have no real production use case -yet, we are not ready to truly vouch for FT232R support. - -More generally: - -* our fteeprom-read tool should be able to read out the EEPROM content from - just about any FTDI chip; - -* our fteeprom-prog tool should be able to program a user-supplied set of bits - into any FTDI+EEPROM combo where the EEPROM is a separate chip, or into FT232R - internal EEPROM - but it most likely won't work for newer FT-X chips; - -* if the goal is to generate a new EEPROM config from scratch, as opposed to - restoring a saved backup, we currently have generators only for FT2232C/D, - for FT2232H and for FT232R, with the last one considered experimental and not - proven. - -libftdi dependency -================== - -We use libftdi (which is in turn layered on libusb) to issue the special USB -control pipe commands to FTDI chips which are needed to read and write their -EEPROMs. We use old-style libftdi-0.x (-lftdi on the link line) as opposed to -libftdi1 (-lftdi1) because the new versions took away the ability to write to -the EEPROM directly with ftdi_write_eeprom_location() calls, forcing users to -go through libftdi1's own EEPROM smarts, which we don't want to do - our tools -are all about more direct user empowerment at the lowest level. - -Selecting the device to operate on -================================== - -Our fteeprom-read, fteeprom-prog and fteeprom-erase tools take a device selector -argument, selecting the device to operate on. This required argument is the -string to be passed to the ftdi_usb_open_string() function in libftdi, allowing -the device to be operated on to be selected in one of several ways. Copying -from libftdi documentation, the available formats are: - -d: - path of bus and device-node (e.g. "003/001") within usb device -tree (usually at /proc/bus/usb/) - -i:: - first device with given vendor and product id, ids can -be decimal, octal (preceded by "0") or hex (preceded by "0x") - -i::: - as above with index being the number of the -device (starting with 0) if there are more than one - -s::: - first device with given vendor id, product id -and serial string - -If you have only one FTDI device connected to your PC or laptop at the time of -your EEPROM manipulation session (generally a good idea to avoid hitting the -wrong device by mistake) and if that FTDI device has some sensible starting -USB VID:PID (either from the previous EEPROM config or the chip's sans-EEPROM -default) that doesn't clash with anything else, then the i: form will probably -be the most convenient, e.g.: - -i:0x0403:0x6001 for single-channel FT232x devices running with the default ID -i:0x0403:0x6010 for dual-channel FT2232x devices running with the default ID -i:0x0403:0xPPPP for custom PIDs assigned out of FTDI's VID range -i:0xVVVV:0xPPPP for totally custom USB IDs - -Or if the current device config is totally hosed (the EEPROM has a passing -checksum, but sets some completely bogus USB ID), then the d: form will -probably be required for recovery. - -Reading the EEPROM -================== - -The basic EEPROM read command is as follows: - -fteeprom-read - -See the previous section for the device selector argument. In this default -form the tool will read the first 64 EEPROM words, which is appropriate for -93C46 external EEPROMs or for the internal 1024-bit EEPROM in the FT232R chip. -However, if you are working with an FT2232x board with an external EEPROM and -that EEPROM is of a larger variety (93C56 or 93C66), this basic form with give -you an incomplete (truncated) read, and you will need one of the following -extended forms to read the complete EEPROM: - -fteeprom-read -b -- read 128 EEPROM words (93C56) -fteeprom-read -B -- read 256 EEPROM words (93C66) - -(If you use one of the extended forms on a smaller EEPROM, you will get 2 or 4 - copies of the same bits.) - -The output of fteeprom-read is in the same format as the input to fteeprom-prog, -thus you can redirect the output to a file and get a restorable backup copy of -your EEPROM. - -It also needs to be noted that if the FTDI device has the kernel's ftdi_sio -driver attached to it (ttyUSB device present) when you run fteeprom-read (same -for fteeprom-prog and fteeprom-erase), the act of running any of our EEPROM -tools will cause it to unbind, i.e., the ttyUSB device will disappear. If the -device being operated on is a dual-channel FT2232x, then only the ttyUSB device -corresponding to Channel A will disappear, while the Channel B ttyUSB device -will stay. +This article has moved; the new location is: -Programming the EEPROM -====================== - -In terms of the primitives provided over USB, writing to EEPROMs sitting behind -FTDI chips is accomplished by writing one 16-bit word at a time: the -SIO_WRITE_EEPROM_REQUEST command writes a user-supplied word at a user-supplied -EEPROM address. However, our fteeprom-prog tool currently supports only writing -complete EEPROMs (64 or 128 or 256 16-bit words starting at address 0) and we -do not currently provide any kind of "random access write" utility; the primary -reason for this design decision is practical usefulness: FTDI's EEPROM structure -includes a checksum over the first 64 words for 1024-bit EEPROMs or over the -first 128 words for larger ones, and if this checksum fails to match, the entire -structure is deemed to be invalid - hence there is no practical use case for -selectively rewriting individual words. The only exception may be with 93C66 -EEPROMs: on these giants only the first half would be subject to the checksum, -and the second half could be used arbitrarily. However, we have not yet -encountered any boards out in the wild with such big EEPROMs, and we have no -plans to use such in any of our own hardware designs either, hence there is no -business case at the present moment to develop tooling support for them. - -There are two primary modes of usage for our fteeprom-prog tool: restoring a -saved EEPROM backup or writing a new EEPROM config which you generate yourself. -To restore a saved EEPROM backup, run the tool as follows: - -fteeprom-prog - -To program a new EEPROM config of your own, run a pipeline of this form: - - | fteeprom-prog - -fteeprom-prog reads the EEPROM image from stdin if no image file is named on -the command line; the image format is the same in both cases, and the length of -this EEPROM image tells the tool how many words need to be programmed - there -are no -b or -B options to fteeprom-prog. - -Generator tools -=============== - -Unfortunately FTDI never documented the format of their EEPROM configuration -structure - apparently they consider it a proprietary trade secret just like -the wire protocol spoken over USB between their chips and their closed-source -proprietary drivers. All FOSS community support for these chips is based on -reverse engineering, and that includes the EEPROM format. - -The present suite of tools includes ftee-gen2232c and ftee-gen2232h EEPROM image -generators, meant for use with FT2232C/D and FT2232H chips, respectively. These -tools are based on the knowledge extracted from other (pre-existing) community -tools, primarily the EEPROM config code built into various libftdi versions - -we haven't done any FTDI RE of our own, instead the goal of this project has -been to create a set of tools that are better fit for production use. - -Our ftee-gen2232c and ftee-gen2232h tools are invoked as follows: - -ftee-gen2232[ch] [-b|-B] [serial-num] - -The output of these generator tools is meant to be piped directly into -fteeprom-prog. - -The philosophy of which settings are given in the config file vs. which ones -are given on the command line reflects configuration management and factory -production line operations. In the envisioned usage there would be a config -file for each product, giving the USB VID:PID, textual manufacturer and product -ID strings and possibly other config settings which need to be changed from the -defaults, but the optional serial number string is given on the command line -because it would be different for each individual unit being programmed. - -The EEPROM size selection is also made on the command line, so that the same -config can be programmed into a smaller EEPROM or a bigger one. By default our -tools generate an image suitable for a 93C46 EEPROM: the generated image is 64 -words long, with a checksum in word 63, and the EEPROM type byte in FTDI's -structure is set to 0x46. Running with -b produces an image for a 93C56 EEPROM: -the EEPROM type byte is set to 0x56, and the checksum-covered image length is -extended to 128 words. Finally, -B sets things up for a 93C66 EEPROM: the -EEPROM type byte is set to 0x66, but the generated checksum-covered image is -still 128 words long just like with -b, as that is what FT2232x chips apparently -expect. I said "apparently" because I don't have any FT2232x hardware with -93C66 EEPROMs and I don't plan on acquiring or building any, hence this minimal -93C66 support is completely untested - use at your own risk. - -It also needs to be noted that with our current RE-based understanding of FTDI's -undocumented EEPROM structure, using a bigger EEPROM does NOT provide more room -for strings: all that happens with -b and -B options is that a gap of 64 unused -EEPROM words is inserted between the end of the fixed structure and the -beginning of strings. The exact same arrangement has been observed in all 93C56 -EEPROM images found in the wild, presumably produced with FTDI's official tools, -including FTDI's own USB-COM232-PLUS2 board - thus it is not clear at all if -FT2232x chips actually support longer strings with bigger EEPROMs, and if not, -what does one need a bigger EEPROM for... - -For the format of config files read by our ftee-gen2232[ch] tools and what -settings can be tweaked, read the source code. - -Erasing the EEPROM (making it blank) -==================================== - -If you are playing with a "generic" FT2232x breakout board that is made for -tinkering, as opposed to a more finished product, such boards are typically -shipped with their EEPROMs completely blank. In that case restoring the EEPROM -to its "pristine" state after playing around would mean erasing it, i.e., -bringing it into a blank (all ones) state. FT2232x chips provide two ways to -do so: one can explicitly write 0xFFFF into each individual EEPROM word with -SIO_WRITE_EEPROM_REQUEST, or one can send a SIO_ERASE_EEPROM_REQUEST command to -the chip, and the chip then erases the entire EEPROM. But we don't know how -the latter SIO_ERASE_EEPROM_REQUEST operation is implemented by FT2232x chips: -does the FT2232x chip go through and erase each word individually, or does it -issue an "erase full chip" opcode to the serial EEPROM? If the latter, then -according to some EEPROM datasheets that operation may not work if the EEPROM -is powered from a 3.3V rail rather than the full USB 5V - may be an issue in -FT2232H-based designs. - -In any case our tools provide both ways. To perform the "automatic full chip -erase" operation, run the following command: - -fteeprom-erase - -To blank the EEPROM by writing 0xFFFF into each word, run one of the following -pipelines: - -ftee-mkblank | fteeprom-prog -- blank a 93C46 EEPROM -ftee-mkblank -b | fteeprom-prog -- blank a 93C56 EEPROM -ftee-mkblank -B | fteeprom-prog -- blank a 93C66 EEPROM +https://www.freecalypso.org/hg/fc-usbser-tools/file/tip/doc/FTDI-EEPROM-tools diff -r e75478dda304 -r df4bf4e06221 doc/USB-IDs --- a/doc/USB-IDs Mon Sep 11 05:24:26 2023 +0000 +++ b/doc/USB-IDs Mon Sep 11 06:51:05 2023 +0000 @@ -1,216 +1,3 @@ -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 -================================== +This article has moved; the new location is: -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. +https://www.freecalypso.org/hg/freecalypso-docs/file/tip/USB-ID-assignments