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.