--- a/README	Wed Aug 30 03:32:06 2023 +0000
+++ b/README	Wed Aug 30 05:39:53 2023 +0000
@@ -1,150 +1,36 @@
-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.
+Welcome to FreeCalypso SIMtrace3
+================================
 
-* 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.
+FC SIMtrace3 (aka SIMtrace-ice) is an alternative implementation of Osmocom
+SIMtrace principal idea, using an iCE40 FPGA instead of AT91SAMx MCU as the ISO
+7816-3 sniffing receiver.  Aside from this change from an MCU to an FPGA and
+thus from firmware to gateware, the other principal difference is that SIMtrace3
+is electrically clean and proper:
 
-* 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.
+* The sniffing apparatus makes a strictly Hi-Z connection to the SIM bus being
+  sniffed;
 
-* 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;
+* The SIM bus itself is solidly connected from the phone's SIM socket to the
+  physical SIM without any switches or pull-ups or other Heisenbug-inducing
+  artifacts;
 
-* 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.
+* The sniffing apparatus supports all 3 voltage classes that can be put out by
+  the ME or other interface device: 1.8V, 3V and 5V are all good.
 
-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.
+The hardware setup of SIMtrace3 consists of:
 
-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.
+* The same SIMtrace FPC cables (going from a SIM socket to the 6-pin FPC
+  connector) that were originally developed for SIMtrace1/2 and are sold by
+  Sysmocom;
 
-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.
+* An off-the-shelf Lattice Icestick FPGA board;
 
-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.
+* A little bit of custom hardware: two very simple boards in the initial
+  version, intending to consolidate them into one board in the final version,
+  see doc/Sniffing-hw-setup for the details.
 
-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.
+This source repository contains:
 
-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.
+boards		Design files for little adapter boards
+fpga		Gateware for the iCE40HX1K FPGA on the Icestick board
+sw		Host software tools

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Motivation	Wed Aug 30 05:39:53 2023 +0000
@@ -0,0 +1,92 @@
+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 than 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.