--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/minnie/doc/Design-spec	Sun Oct 01 07:01:56 2023 +0000
@@ -0,0 +1,342 @@
+FreeCalypso Minnie GSM MS development board
+Design specification
+
+0. Purpose
+
+FC Minnie board is being produced for one primary purpose: to provide an
+alternative to the horrible (in the opinion of the Mother of FreeCalypso)
+GTM900-based application board design being developed by Sysmocom in the
+project identified as OS#4030.  A situation in which the Horribilis board is
+readily and cheaply available to the worldwide GSM hacker/enthusiast community
+yet no better alternatives are available would be an unacceptable travesty,
+hence I (Mother Mychaela) feel a moral imperative to develop, produce and make
+available a better board, even though this venture will almost certainly come
+at a loss in economic terms.
+
+1. Overview of proposed new board
+
+FC Minnie will be a single PCBA featuring the following key components:
+
+* FC Tango module containing the Calypso GSM MS core;
+* RF plumbing, terminating in a standard SMA female connector hanging off
+  the edge of the board;
+* A standard SIM 2FF socket;
+* A USB subsystem built around FT2232H, providing two UART channels behind
+  a single USB device.
+
+The principal way of operating this board will be via USB-carried UARTs: the
+operator will need to connect USB between her computer and FC Minnie board, and
+two ttyUSB devices will appear, corresponding to Calypso Modem and IrDA UARTs.
+
+FC Minnie is intended to be a GSM MS board of modem rather than handset type:
+there are no hw provisions for connecting phone UI peripherals such as an LCD
+or a keypad, and the board is NOT designed to operate untethered, without a
+host computer connected via USB.  FreeCalypso family of projects includes a
+plan for a different GSM MS board, named FC Venus, that will be designed to run
+untethered with a 176x220 pixel LCD and a keypad matching the legendary
+historical D-Sample board from TI - but FC Venus will be an expensive board,
+reserved for those who truly share the Mother's vision for FreeCalypso, and
+cannot compete with the OS#4030 application board coming out of Sysmocom.
+
+1.1. Powering arrangement
+
+The board will consist of two separate power domains: GSM and USB.  The GSM
+domain will require a separate power supply, and cannot be powered from USB.
+The battery-emulating power supply for the GSM MS core will be the same as used
+for FCDEV3B and Caramel2 boards, with the same FC-standard power connector.
+FreeCalypso HQ already has a large batch of these power supplies that were made
+for us on a semi-custom basis, and we can provide them at a cost of about $7
+per unit - hence from the cost perspective, there is no justification for
+breaking FreeCalypso tradition and changing the design to a different powering
+arrangement,
+
+OTOH, USB will be the sole source of power for the FT2232H subsystem - if there
+is no USB host connected, this subsystem will be unpowered.
+
+1.1.1. Power domain boundary crossing
+
+With USB and GSM sides of the board separately powered, there are two partial
+power-down (PPD) scenarios to be concerned with:
+
+PPD1: The USB host is plugged in, but there is no battery-emulating power supply
+connected, or the GSM MS power supply is connected, but the chipset is in its
+switched-off state per Iota VRPC.
+
+PPD2: The GSM MS power supply is connected and the chipset is switched on in the
+soft power switching sense, but there is no USB host connected and the FT2232H
+subsystem is unpowered.
+
+PPD2 is an error case: because this board is not designed to operate untethered,
+the combination of booting the Calypso chipset and its flashed firmware without
+a connected USB host is invalid.  However, this combination can happen very
+easily by mistake, hence the hardware needs to handle it without entering a
+state in which it would be subjected to serious adverse conditions such as
+excessive current flow.  OTOH, PPD1 is a scenario that is expected to occur all
+the time in standard FreeCalypso workflows: the USB host is connected but the
+chipset has not been commanded to switch on yet, or the GSM MS has executed a
+soft poweroff but the USB host hasn't been unplugged yet.
+
+The set of LVC buffers inserted between FT2232H and Calypso I/O pins is expected
+to provide correct graceful handling of both PPD scenarios, as detailed in
+section 2.1.
+
+1.2. FT2232H USB subsystem
+
+Standard FreeCalypso workflows require that both Calypso UARTs be connected to
+the development host side by side.  In the olden days of TI's own developers
+working in TI offices with D-Sample and earlier development boards, the GSM MS
+board would bring out two DE9F RS-232 ports, engineers had desktop PCs outfitted
+with special multiport serial cards, and there was a pair of RS-232 cables for
+each GSM MS development board.  In the present day USB is a much more practical
+alternative, and the need to have both Calypso UARTs presented to the developer
+side by side translates into a requirement for a two-channel USB-serial chip
+that goes from one USB device to two UART channels.  Additional requirements
+for this two-channel USB-serial chip are:
+
+* The two channels should be symmetric from the chip's PoV, so that the choice
+  of which channel goes to which Calypso UART can be made by FreeCalypso
+  convention.  The latter convention says that in the absence of other ttyUSB
+  devices, ttyUSB0 shall be Calypso Modem UART (AT command channel) and ttyUSB1
+  shall be Calypso IrDA UART (rvinterf channel).
+
+* The USB-serial chip needs to support non-standard baud rates, including an
+  ability to handle 203125/406250/812500 bps, and this support should be
+  available on both channels, so that no additional constraints are imposed on
+  possible developer workflows.
+
+Out of the repertoire of USB-serial chips which I (Mother Mychaela) am familiar
+with, only FT2232x (either FT2232C/D or FT2232H) fit the bill.  My original
+preference was for FT2232D, but that chip has just been discontinued, thus
+FT2232H will have to be used instead.
+
+1.3. Tango module signal bring-out trade-offs
+
+The complete set of signals coming out of FC Tango module via its 80-pin system
+interface connector is very rich, with most Calypso and Iota chipset signals
+included.  Caramel-type boards (iWOW DSK and FC Caramel2) make all of these
+signals accessible for play, with most of them going to the expansion interface
+on a 56-pin header - but these boards cannot compete for the lowest possible
+cost market niche.  Therefore, a board that is intended to compete with the
+Horribilis board of OS#4030 on the metric of cost needs to be reduced in scope,
+giving up advanced capabilities of FC Tango and providing only basic, modem-type
+GSM MS functionality.
+
+Out of the rich signal set coming out of FC Tango, only two non-essential
+interfaces are brought out on FC Minnie: the main analog audio channel (see
+section 2.7) and Calypso MCSI for digital audio (see section 2.8).  Those who
+are interested in additional Calypso+Iota chipset signals available on FC Tango
+will need to use a Caramel2 board, for as long as those remain in surplus, to be
+succeeded later by another board tentatively named EvaTango, following TI's
+original naming convention for component evaluation boards.
+
+2. Detailed design
+
+2.1. Dual UART interface across power domains
+
+2.1.1. Signals from FT2232H to Calypso
+
+There are 4 signals that need to connect in this direction (names from host DTE
+perspective): TxD, RTS, DTR and TxD2.  If these signals were to be connected
+directly between the two chips, there would be undesirable effects:
+
+* FT2232H I/O operates at 3.3V; this voltage level is acceptable for Calypso I/O
+  pins (CAL000/A spec says VDDS + 0.5 V, accounting for the forward drop voltage
+  of clamping diodes inside the chip), but is not ideal.
+
+* The main issue is partial power-down scenario PPD1, defined in section 1.1.1.
+  If the outputs of a powered USB-serial chip are connected directly to I/O pins
+  of an unpowered Calypso, current would feed from these outputs through Calypso
+  I/O clamping diodes into the Calypso+Iota chipset's V-IO rail.  Series
+  resistors can limit this current to a safe value, but we now know through
+  experience that the only way to produce correct indicator LED behaviour is to
+  eliminate this wayward current completely.
+
+The solution is to insert an LVC buffer IC (either 74LVC125A or 74LVC541A) into
+these 4 signal paths; this buffer IC needs to be powered from the Calypso+Iota
+chipset's V-IO rail, which is brought out from FC Tango module.  With this LVC
+buffer and the Calypso chip's I/O ring powered by the same supply rail, there is
+no power domain boundary at Calypso inputs, and instead this boundary is moved
+to the inputs of the LVC buffer.  Unlike Calypso and other common ASICs, LVC
+logic ICs have special input and output structures that are specifically
+designed for PPD applications, with a guaranteed very low Ioff spec.  LVC logic
+family is also specifically designed to tolerate input voltages higher than the
+IC's own supply, up to 5V - thus our 3.3V is well within safe design margins.
+
+Buffer-translated DTR signal will go to Calypso GPIO3 per conventions of TI,
+iWOW and FreeCalypso.  A 2.2 kOhm series resistor can be inserted in this path,
+solely to protect the hardware from software misconfiguration, in case someone
+erroneously configures this Calypso GPIO as an output.
+
+No pull resistors will be placed on the nets running from FT2232H outputs to
+LVC buffer inputs.  In erroneous scenario PPD2 all LVC buffer inputs in this
+direction and thus all Calypso UART inputs will sense logic low: LVC buffer
+inputs appear at first glance to be floating, but they cannot reach anywhere
+near the switching threshold, as any accumulated stray voltages will discharge
+toward GND through the unpowered FT2232H chip's clamping diodes.
+
+Having Calypso UART inputs sense low rather than high is not desirable, but
+scenario PPD2 can only be an error case on this board, hence there is no
+justification to expend more components and PCB real estate on a more
+complicated circuit design (see FC Venus for example) that would produce logic
+high levels at Calypso UART inputs in this scenario.
+
+2.1.2. Signals from Calypso to FT2232H
+
+There are 5 signals that need to connect in this direction (names from host DTE
+perspective): RxD, CTS, DCD, RI and RxD2.  Just like in the case of signals
+going the other way, connecting these signals directly between the two chips
+would be problematic:
+
+* Scenario PPD2: clamping diodes in the unpowered FT2232H chip will turn that
+  chip's inputs (driven by Calypso outputs) into shorts to GND, thus Calypso
+  outputs would be severely overloaded with high current flow.  This scenario
+  is an error condition, but because it is very easily caused, we would rather
+  not overstress the hw in this condition.
+
+* Scenario PPD1: experience with Caramel2 boards shows that pull-up resistors
+  on USB-UART inputs, including internal pull-ups inside FT2232x chips, can
+  sometimes leak enough current into the clamping diodes of directly connected
+  Calypso I/O pins to create visibly incorrect state on indicator LEDs.
+
+The solution is to insert an LVC buffer IC (74LVC541A is needed here) into these
+5 signal paths as well.  Which supply should this buffer IC be powered from:
+Calypso V-IO or USB domain 3.3V?  Either option is expected to solve the LED
+problem in scenario PPD1 (no path for current from the USB domain to flow into
+the V-IO rail), but other considerations differ:
+
+* If this LVC buffer is powered from Calypso V-IO, all FT2232H inputs will sense
+  logic high (from the chip's internal pull-ups) in scenario PPD1.  However,
+  the high current problem of scenario PPD2 is not only left unsolved, but made
+  potentially worse, as LVC buffers have much higher drive strength than Calypso
+  outputs.
+
+* If this LVC buffer IC is powered from USB domain 3.3V rail, scenario PPD2 is
+  solved: the interface between power domains occurs at a point where outputs
+  from one domain hit Ioff-specified LVC buffer inputs in the other domain.
+  However, in scenario PPD1 all FT2232H inputs will sense logic low rather than
+  high: the LVC buffers will sense logic low inputs by the same seemingly-
+  floating mechanism as in the previous section, and they will propagate this
+  logic low to FT2232H inputs.
+
+Logic low at LVCMOS-level (as opposed to RS-232 levels) UART inputs means a
+break condition on the data line and asserted state for all control signals.
+Having this state at host UART input when the target is unpowered and waiting
+to be switched on is counter to usual conventions, but creating the opposite
+(more conventional) state in this scenario without causing any other problems
+with the interdomain interface would require significant extra circuit
+complexity, translating into extra cost.  Thus breaking some customary
+conventions about UARTs appears to be the appropriate compromise here.
+
+2.2. Indicator LEDs
+
+There will be 3 indicator LEDs on FC Minnie board: one green, one yellow and
+one red, described in the following sections.
+
+2.2.1. Green power-on status LED
+
+FCDEV3B features a green LED that lights when the Calypso+Iota chipset is
+switched on and goes out at other times.  The way in which this LED is
+implemented on FCDEV3B is completely impervious to wayward current feeding into
+the V-IO rail, hence the issue of this current feeding from USB power domain
+never caused a problem on that board.  However, the method used on FCDEV3B
+cannot be used on any board using a packaged modem module like iWOW-based Tango
+or Huawei GTM900: the internal signal used for LED control on FCDEV3B is not
+brought out by anyone.
+
+The plan for FC Minnie is to control the green LED with V-IO.  Putting a LED
+plus a series resistor directly between V-IO and GND (powering the LED from
+V-IO) would be a bad idea: when the Calypso+Iota chipset enters superdeep sleep,
+the current budget of Iota regulator VRIO reduces to just 1 mA, which is too
+little for a LED.  The plan for FC Minnie is to control this LED with the same
+"digital transistor" (BJT plus bias resistors) circuit as used for the PWL LED
+on Caramel2 (see section 2.2.3), but with V-IO in the place of PWL signal.
+With 10 kOhm base resistor the load on V-IO is limited to 280 uA, yet the LED
+(powered from raw VBAT) gets enough current to be visibly lit.
+
+In order for this plan to produce the desired result of this LED lighting when
+the Calypso+Iota chipset is switched on and going out upon soft poweroff, there
+must not be _any_ wayward current feeding into the V-IO rail from the USB power
+domain by any path.  The Mother's hope is that the buffer design of section 2.1
+will work as intended and give us a reliable switch-on state indicator LED.
+
+2.2.2. Yellow CLK13M status LED
+
+FC Caramel2 board introduced an innovation: a yellow LED that lights when CLK13M
+(brought out on FC Tango) is running and goes out when this clock is stopped
+(chipset off or in deep sleep), causing this LED to flash when standard
+FreeCalypso firmware with all sleep modes enabled is in idle mode listening on
+PCH.  Unfortunately on some Caramel2 boards this LED would also light
+erratically in scenario PPD1: when the V-IO rail rises above 0V as a result of
+wayward current feeding while other Calypso power supplies are off, sometimes
+Calypso outputs behave erratically, and some may unexpectedly drive high,
+causing LEDs to turn on.
+
+The plan is to replicate the CLK13M status LED circuit from Caramel2 verbatim
+on FC Minnie; the hope is that the new design of section 2.1 will eliminate the
+problem of wayward V-IO feeding and the LED will become fully reliable.
+
+2.2.3. Red PWL LED
+
+The remaining LED from FC Caramel2, a red LED controlled by Calypso PWL output,
+will also be copied verbatim on FC Minnie, and the same hope as in section 2.2.2
+applies here too.
+
+Calypso PWL allows the intensity of light to be smoothly controlled by software,
+and standard FC firmware exports this control to the user in the form of AT@PWL
+command.  AT@PWL=0 turns this LED off, AT@PWL=255 turns it on at full
+brightness, and all intermediate levels produce intermediate brightness.
+
+2.3. Target boot control
+
+FC Tango module brings out PWON and RESET boot control signals, although no
+RPWON.  FC Minnie will provide both manual (tactile switches) and programmatic
+boot control options.  There will be two manually operated buttons on the board,
+PWON and RESET, and there will also be support for programmatic boot control
+like on DUART28C.
+
+DUART28C-style host-based boot control mechanism repurposes otherwise unused
+RTS and DTR outputs of FT2232x Channel B, the UART channel that goes to the
+data leads only Calypso debug UART.  The circuit consists of a pair of OD
+drivers packaged in one 74LVC2G07 chip, with RTS driving PWON and DTR driving
+RESET.
+
+Correct operation with these circuit connections in place requires programming
+a custom USB ID code into FT2232x EEPROM (see section 2.4) and patching the
+Linux kernel ftdi_sio driver to apply a special quirk upon seeing this USB ID.
+An additional complication is that Linux USB and tty subsystem maintainers are
+refusing to mainline this quirk-adding patch, thus end users need to apply this
+patch on their own systems in an act of principled defiance against obstinent,
+assinine and tyrannical maintainers.
+
+Because of these complications, this DUART28C-style boot control circuit needs
+to be made optional.  The simplest solution is a pair of jumpers: the net from
+the OD driver on Channel B RTS to Tango PWON will pass through one user-
+removable jumper (2.54 mm header pin pair with a removable shorting block), and
+the net from the OD driver on Channel B DTR to Tango RESET will pass through
+another such jumper.
+
+2.4. FT2232H USB subsystem details
+
+The USB connector will be of mini-B type like on all other classic development
+boards targeting this hacker community; the circuit from this USB connector to
+FT2232H chip will be as prescribed by FTDI.  An external LDO regulator bringing
+the bus-powering voltage from 5V down to 3.3V will need to be implemented, as
+always required with FT2232H, and all components are then powered from this 3.3V
+supply.
+
+The FT2232H subsystem will include a 93C46 EEPROM.  FT2232H can work without an
+EEPROM, but I as the Mother of FreeCalypso insist on always including this
+configuration EEPROM.  FC Minnie will need to have a custom USB ID programmed
+in this EEPROM when the two remote boot control jumpers are installed, and with
+both PID options the EEPROM will always be programmed with custom textual ID
+strings, allowing the board to be recognized among other USB devices sharing
+the same VID:PID.
+
+2.5. RF plumbing
+
+2.6. SIM socket
+
+2.7. Analog audio
+
+2.8. Digital audio
+