--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Mon Jul 17 00:52:00 2023 +0000
@@ -0,0 +1,150 @@
+Alternative implementation of SIMtrace idea,
+using iCE40 FPGA instead of AT91SAMx
+============================================
+
+Q: What is the principal idea behind SIMtrace, as distinct from the specific
+implementation realized by "standard" Osmocom SIMtrace?
+
+A: The two principal objectives of SIMtrace are:
+
+1) Passive sniffing of communication between a phone-type device and a SIM,
+   ideally as transparent and non-invasive as possible.
+
+2) Card emulation: the SIMtrace apparatus presents itself to the phone (or
+   modem or other phone-type device) as a SIM, either emulating the entire
+   SIM CardOS functionality in software or communicating with a real SIM
+   located somewhere remotely, across the Internet.
+
+Q: What are the shortcomings of the existing Osmocom SIMtrace implementation of
+   the above goals?
+
+A: In the opinion of Mother Mychaela of FreeCalypso, the electrical aspects of
+   Osmocom SIMtrace implementation are its biggest shortcoming.  The following
+   problems are most acute currently:
+
+* Current SIMtrace v2 hardware is not 5V-tolerant: connecting this apparatus to
+  an old phone that puts out 5V (class A) on its SIM socket can damage the
+  hardware, as class A SIM voltages exceed the absolute maximum rating spec of
+  the AT91SAM3S4B microcontroller on the SIMtrace v2 board, which is connected
+  directly to the SIM bus.
+
+* One option would be to revive the previous hardware generation as in SIMtrace
+  v1, replacing the AT91SAM3S with AT91SAM7S.  However, all firmware maintained
+  by Osmocom is written for SAM3S only, thus a backport to SAM7S would involve
+  significant work.  Given that the resulting solution would still be far from
+  my idea of perfection, I find it difficult to justify investing in that
+  software effort - instead I would rather work on a more philosophically-proper
+  solution.
+
+* AT91SAMx-based SIMtrace, both v1 and v2, works (most of the time, but not 100%
+  reliably) with 1.8V phone-SIM combination (a phone that prefers class C and a
+  SIM that supports it) only by accident.  The Vih spec (the minimum required
+  voltage on a signal line for it to register reliably as a 1) is 2.0 V for
+  AT91SAM7S or 2.31 V (0.7 * Vddio, Vddio = 3.3 V) for AT91SAM3S, but the actual
+  voltage on SIM interface lines in class C operation will never rise above
+  1.8 V.  The electrical interface on this hw operates severely out of spec,
+  and I find it rather miraculous that it works at all.  Not surprisingly,
+  reports are starting to trickle in with user experiences of it actually NOT
+  working sometimes.
+
+* Even if the SIM interface is restricted (by the phone, by the SIM, or by
+  SIMtrace MITM function tampering with ATR or file characteristics bytes) to
+  operating in class B (3.0 V nominal) only, the existing AT91SAMx SIMtrace
+  boards are still electrically unclean.  Looking at the schematics, one can see
+  that both CLK and I/O lines are pulled up (with resistors) to the SIMtrace
+  board's 3.3V rail, which is a higher voltage that what the phone will put out
+  (3.0 V or 1.8 V), and in the case of SIMtrace v1 with a 5V phone, that pull-up
+  will turn into a pull-midway-down instead.
+
+* My philosophy is that the tracing apparatus should be making only a high-
+  impedance connection to the SIM bus and nothing more, while the SIM bus itself
+  is galvanically connected from the phone to the physical SIM without passing
+  through any switches or other potential Heisenbug-inducing artifacts.
+
+My first thought was to gently modify the existing AT91SAMx-based SIMtrace
+design for electrically clean multivolt operation:
+
+* Replace the electrical switches for SIM VCC (FPF2109) and SIM RST/CLK/IO
+  (CB3Q3244) with either a relay (my initial thought, but way too power-hungry)
+  or a manually operated 5PDT slide switch;
+
+* Insert a Nexperia 74LVC4T3144 dual-supply buffer between the SIM bus and the
+  MCU, providing a sniffing path that not only supports all 3 voltage classes,
+  but is electrically clean, making only a high-impedance connection to the SIM
+  bus as I desire;
+
+* Connect a 74LVC1G07 open drain driver (fed with TxD from the MCU) to the SIM
+  bus I/O line, providing a signal path for card emulation mode.  (In trace mode
+  the firmware would be responsible for never turning on this OD driver, keeping
+  the tracing apparatus High-Z.)
+
+However, as I was reading AT91SAMx datasheets more carefully in preparation for
+embarking on a project to turn the above idea into reality, I saw a big problem:
+when the USART is put into ISO 7816-3 mode, it uses the chip's TxD pin (switched
+to open drain operation) for both Rx and Tx, and there is no option to keep
+separate RxD and TxD pins with an external receiving buffer and an external OD
+driver.
+
+It would probably be possible to build an all-voltage SIM interface with
+AT91SAMx, perhaps by using one of those bidirectional level shifter ICs that
+somehow automagically handle driving direction reversals.  But I personally am
+not too inclined to trust those automagical bidirectional translators, they
+just don't align with my design philosophy - I would much much rather have
+unidirectional buffers, one for sniffing and another for OD-driving the I/O
+line in card emulation mode.  Seeing that AT91SAMx is incompatible with such
+electrical design, I decided to screw AT91SAMx and go for a radically different
+approach.
+
+Outline of FPGA-based alternative design
+========================================
+
+My (Mother Mychaela's) idea of alternative SIMtrace implementation consists of
+the following pieces:
+
+1) The passive SIMtrace FPC connection board (boards/sim-fpc-pasv) is a trivial
+   PCB that electrically interconnects a SIM socket, an FPC connection for
+   SIMtrace FPC cables and a set of 2.54 mm header pins bringing out all SIM
+   interface signals.
+
+2) A second little adapter board (tentatively named mv-sniffer) will feature one
+   active component, but will still be just as trivial: it will be a PCB hosting
+   a single 74LVC4T3144 IC, with 2.54 mm header pins for the SIM side (SIM VCC
+   will go to the buffer IC's VccA) and for the FPGA board side; a power rail
+   from the latter board will go to the buffer IC's VccB.
+
+3) The FPGA board will be an off-the-shelf item, eliminating the major hurdle
+   of having to design and build a custom board of substantial complexity.  My
+   first attempt will be to use the Icestick board with iCE40HX1K FPGA; if this
+   FPGA proves to be too small, I will then look for another suitable board
+   with a bigger FPGA.
+
+The Icestick board features not only the HX1K FPGA, but also an FT2232H chip
+handling the USB interface.  FT2232H channel A is for FPGA programming, but
+channel B is a regular UART, connected with PCB traces to FPGA I/O pins for
+user logic.  The logic implemented in the FPGA will use this UART interface to
+communicate with higher-level software, which will be implemented as simple
+userspace programs - thus there is no "firmware" component per se.
+
+In terms of FPGA gateware functionality, the passive sniffer function will be
+implemented first; once it works, a different logic design will be implemented
+for card emulation mode.
+
+In terms of hardware as in boards, the first prototype version will use separate
+sim-fpc-pasv and mv-sniffer boards, connected with jumper wires between 2.54 mm
+header pins.  Because the signals carried by these jumper wires reside on the
+"target" SIM bus side of the buffer, these wires add more than just clutter -
+they also add to the electrical length of the external SIM bus, which is
+obviously bad.  Once the basic design is proven good, I plan to spin out another
+simple board that will feature the SIM socket, the SIMtrace FPC connector, the
+74LVC4T3144 buffer and a header for connecting to the FPGA board.  Because the
+latter connection resides past the buffer, wire length here does NOT add to the
+SIM bus.
+
+All of the just-described hardware config is for tracing only, not for card
+emulation.  For the latter function yet another, albeit still very simple,
+adapter board will need to be made.  The cardem adapter board will feature the
+SIMtrace FPC connector, two active ICs (74LVC4T3144 receiving buffer and
+74LVC1G07 OD driver) and the header for connecting to the FPGA board.  Note the
+absence of a SIM socket - hardware setups for sniffing a phone's communication
+with a real SIM on the one hand and for running with a software-emulated SIM on
+the other hand are different, and it does no good trying to combine them.