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.