--- /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.