--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Serial-SIM-readers	Sun Mar 21 04:32:18 2021 +0000
@@ -0,0 +1,118 @@
+A serial SIM reader is a very simple hardware gadget consisting of just the
+following:
+
+* An always-on power supply (voltage determined by hw design) connected to SIM
+  VCC contact;
+
+* An always-on fixed-frequency clock fed to SIM CLK contact;
+
+* SIM I/O line connected to both TxD and RxD of a general-purpose UART, with
+  UART TxD driving SIM I/O by way of an open collector or open drain buffer;
+
+* SIM RST line controlled by one of the modem control lines, either DTR or RTS.
+
+In order to successfully communicate with the SIM, the UART baud rate needs to
+be set to clock_freq/372, where clock_freq is the clock frequency fed to SIM CLK
+contact, determined by the crystal oscillator used in the design of the serial
+SIM reader gadget.  This baud rate must be used initially for receiving ATR and
+performing PTS, and it can also be used for the entire card session if the user
+is content with the default slow speed - however, if the SIM card supports speed
+enhancement (almost all cards do), this speed enhancement feature can be
+supported with serial SIM readers if the UART baud rate can be switched under
+software control from clock_freq/372 to clock_freq/64.
+
+I (Mother Mychaela) am a very late comer to this game, thus I am not able to
+speak with authority regarding the history of how serial SIM readers came about.
+However, my understanding of this history is that early serial SIM readers were
+RS-232 serial rather than USB-serial, thus they were constrained to use only
+standard RS-232 baud rates like 9600 bps.  And even when "serial" SIM readers
+are really USB-serial, with a USB UART chip built directly into the custom
+gadget, most people are still used to standard RS-232 baud rates (and the most
+important OSes still make it unreasonably difficult to use non-standard baud
+rates on USB-serial and other ports that are capable of such), thus the classic
+baud rate of 9600 bps has stuck.
+
+When a serial SIM reader gadget is designed to operate at 9600 baud, the crystal
+oscillator frequency should ideally be 3.571200 MHz: 9600 * 372 = 3571200.
+However, most real-life serial SIM readers out there have been built in a "race
+to the bottom" fashion in terms of cost, and they typically feature crystals of
+some frequency that is close to the ideal one, but not exactly - apparently
+crystals of other nearby frequencies are cheaper than getting one for the ideal
+frequency of 3.571200 MHz.  (As a practical example, the USB-serial SIM reader
+I bought on ebay in 2021-03 features a 3.579545 MHz crystal.)  These serial SIM
+readers with slightly-off crystals exploit the baud rate error tolerance that is
+inherent in all UART interfaces.
+
+The use of 3.571200 MHz (or close to this frequency) clocks in USB-serial SIM
+reader designs is a case of conservative thinking, as opposed to maximizing
+speed.  The highest clock frequency allowed by SIM card specs is 5 MHz for
+class A (5.0 V) or 4 MHz for classes B and C (3.0 V and 1.8 V), thus if someone
+sought maximum SIM communication speed, they could use a higher frequency clock
+(for example, the same 4.8 MHz clock that is used in the USB CCID reader on
+which I measured it with an oscilloscope, HID Omnikey 3121), use a high-quality
+USB-serial chip with good support for non-standard baud rates, and design the
+software around the resulting non-standard baud rates, including baud rate
+switching for SIM speed enhancement.  If anyone has ever made such a USB-serial
+SIM reader, our tools are ready to support it - but I don't know if anyone has
+ever built such a gadget.
+
+In case of serial SIM readers with 3.571200 MHz (or nearby) clocks, it is my
+(Mychaela's) guess that their designers probably never considered the
+possibility of using SIM speed enhancement, and that most programmers who write
+software tools for such readers don't consider it either, resigning themselves
+to just the default slow speed mode of F=372 D=1.  However, if the SIM card
+supports F=512 D=8 speed enhancement (almost all cards do) and this mode is
+activated via PTS procedure, the baud rate becomes 55800 bps.  This baud rate
+is non-standard - however, the USB-serial chip in the SIM reader gadget I got
+from ebay supports it just fine.  (The USB-serial chip in this particular reader
+is a PL2303, so I initially thought that it wouldn't support non-standard baud
+rates - however, a closer investigation revealed that the popular notion of
+these chips not supporting non-standard baud rates is actually a myth: PL2303
+chips support non-standard baud rates just fine, instead this support was
+lacking in earlier versions of the Linux kernel pl2303 driver.)
+
+Our FC SIM tools back end for serial SIM readers supports 55800 baud speed
+enhancement mode whenever the UART and its Linux kernel driver support it, and
+we also support even higher speed enhancement modes: if the UART can handle
+111600 baud, we can use F=512 D=16 mode, and if the UART can handle 223200 baud,
+we can use F=512 D=32 mode which most newer SIM cards support.  And yes, the
+PL2303 USB-serial chip in the SIM reader I got from ebay supports this fastest
+223200 baud mode just fine.
+
+Using fc-simtool with serial SIM readers
+========================================
+
+The most basic usage is as follows:
+
+fc-simtool -d /dev/ttyXXX
+
+If the serial SIM reader uses a 3.571200 MHz (or nearby frequency) crystal and
+you are not going for speed enhancement (i.e., if you are sticking with 9600
+baud for the entire card session), then no further options are needed.
+
+If the clock frequency stays at 3.571200 MHz (or nearby) but you do wish to use
+speed enhancement, add one of the following options:
+
+-e1 if your UART can handle 55800 bps;
+-e2 if your UART can handle 55800 and 111600 bps;
+-e4 if your UART can handle 55800, 111600 and 223200 bps.
+
+The actual selected mode will be based both on the UART capabilities declared
+with the -e option and on the SIM card capabilities indicated in the ATR TA1
+byte.
+
+If your serial SIM reader uses a different clock frequency such that you need to
+use baud rates other than 9600 and 55800 bps for standard and speed-enhanced
+modes, respectively, then you need to use the more general -b option instead of
+-e, taking one of the following forms:
+
+-b base_baud
+-b base_baud,spenh_baud
+-b base_baud,spenh_baud,spenh_max
+
+base_baud is the initial baud rate to use for receiving ATR; if no further
+comma-separated parameters are specified, then this initial baud rate persists
+for the entire card session without any speed enhancement modes.  spenh_baud is
+the baud rate to use for F=512 D=8 speed enhancement mode.  spenh_max must be
+1, 2, 4 or 8 (the default is 1); it is the maximum further multiplier that can
+be applied to spenh_baud, if any.