FreeCalypso > hg > fc-sim-tools

annotate doc/Serial-SIM-readers @ 59:10bfdee30a68

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
simtool/chvext.c: missing #include <stdlib.h>
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 23 Mar 2021 05:25:12 +0000
parents b0cf75d0bb2d
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
47
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 A serial SIM reader is a very simple hardware gadget consisting of just the
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 following:
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 * An always-on power supply (voltage determined by hw design) connected to SIM
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 VCC contact;
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 * An always-on fixed-frequency clock fed to SIM CLK contact;
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 * SIM I/O line connected to both TxD and RxD of a general-purpose UART, with
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 UART TxD driving SIM I/O by way of an open collector or open drain buffer;
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 * SIM RST line controlled by one of the modem control lines, either DTR or RTS.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 In order to successfully communicate with the SIM, the UART baud rate needs to
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 be set to clock_freq/372, where clock_freq is the clock frequency fed to SIM CLK
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 contact, determined by the crystal oscillator used in the design of the serial
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 SIM reader gadget. This baud rate must be used initially for receiving ATR and
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 performing PTS, and it can also be used for the entire card session if the user
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 is content with the default slow speed - however, if the SIM card supports speed
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 enhancement (almost all cards do), this speed enhancement feature can be
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 supported with serial SIM readers if the UART baud rate can be switched under
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 software control from clock_freq/372 to clock_freq/64.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 I (Mother Mychaela) am a very late comer to this game, thus I am not able to
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 speak with authority regarding the history of how serial SIM readers came about.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 However, my understanding of this history is that early serial SIM readers were
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 RS-232 serial rather than USB-serial, thus they were constrained to use only
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 standard RS-232 baud rates like 9600 bps. And even when "serial" SIM readers
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 are really USB-serial, with a USB UART chip built directly into the custom
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 gadget, most people are still used to standard RS-232 baud rates (and the most
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 important OSes still make it unreasonably difficult to use non-standard baud
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 rates on USB-serial and other ports that are capable of such), thus the classic
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 baud rate of 9600 bps has stuck.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 When a serial SIM reader gadget is designed to operate at 9600 baud, the crystal
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 oscillator frequency should ideally be 3.571200 MHz: 9600 * 372 = 3571200.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 However, most real-life serial SIM readers out there have been built in a "race
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 to the bottom" fashion in terms of cost, and they typically feature crystals of
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 some frequency that is close to the ideal one, but not exactly - apparently
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 crystals of other nearby frequencies are cheaper than getting one for the ideal
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 frequency of 3.571200 MHz. (As a practical example, the USB-serial SIM reader
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 I bought on ebay in 2021-03 features a 3.579545 MHz crystal.) These serial SIM
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 readers with slightly-off crystals exploit the baud rate error tolerance that is
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 inherent in all UART interfaces.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 The use of 3.571200 MHz (or close to this frequency) clocks in USB-serial SIM
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 reader designs is a case of conservative thinking, as opposed to maximizing
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 speed. The highest clock frequency allowed by SIM card specs is 5 MHz for
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 class A (5.0 V) or 4 MHz for classes B and C (3.0 V and 1.8 V), thus if someone
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 sought maximum SIM communication speed, they could use a higher frequency clock
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 (for example, the same 4.8 MHz clock that is used in the USB CCID reader on
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 which I measured it with an oscilloscope, HID Omnikey 3121), use a high-quality
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 USB-serial chip with good support for non-standard baud rates, and design the
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 software around the resulting non-standard baud rates, including baud rate
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 switching for SIM speed enhancement. If anyone has ever made such a USB-serial
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 SIM reader, our tools are ready to support it - but I don't know if anyone has
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 ever built such a gadget.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 In case of serial SIM readers with 3.571200 MHz (or nearby) clocks, it is my
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 (Mychaela's) guess that their designers probably never considered the
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 possibility of using SIM speed enhancement, and that most programmers who write
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 software tools for such readers don't consider it either, resigning themselves
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 to just the default slow speed mode of F=372 D=1. However, if the SIM card
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 supports F=512 D=8 speed enhancement (almost all cards do) and this mode is
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 activated via PTS procedure, the baud rate becomes 55800 bps. This baud rate
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 is non-standard - however, the USB-serial chip in the SIM reader gadget I got
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 from ebay supports it just fine. (The USB-serial chip in this particular reader
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 is a PL2303, so I initially thought that it wouldn't support non-standard baud
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 rates - however, a closer investigation revealed that the popular notion of
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 these chips not supporting non-standard baud rates is actually a myth: PL2303
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 chips support non-standard baud rates just fine, instead this support was
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 lacking in earlier versions of the Linux kernel pl2303 driver.)
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 Our FC SIM tools back end for serial SIM readers supports 55800 baud speed
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 enhancement mode whenever the UART and its Linux kernel driver support it, and
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 we also support even higher speed enhancement modes: if the UART can handle
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 111600 baud, we can use F=512 D=16 mode, and if the UART can handle 223200 baud,
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 we can use F=512 D=32 mode which most newer SIM cards support. And yes, the
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 PL2303 USB-serial chip in the SIM reader I got from ebay supports this fastest
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 223200 baud mode just fine.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 Using fc-simtool with serial SIM readers
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 ========================================
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 The most basic usage is as follows:
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 fc-simtool -d /dev/ttyXXX
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 If the serial SIM reader uses a 3.571200 MHz (or nearby frequency) crystal and
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 you are not going for speed enhancement (i.e., if you are sticking with 9600
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 baud for the entire card session), then no further options are needed.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 If the clock frequency stays at 3.571200 MHz (or nearby) but you do wish to use
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 speed enhancement, add one of the following options:
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 -e1 if your UART can handle 55800 bps;
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 -e2 if your UART can handle 55800 and 111600 bps;
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 -e4 if your UART can handle 55800, 111600 and 223200 bps.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 The actual selected mode will be based both on the UART capabilities declared
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 with the -e option and on the SIM card capabilities indicated in the ATR TA1
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 byte.
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 If your serial SIM reader uses a different clock frequency such that you need to
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 use baud rates other than 9600 and 55800 bps for standard and speed-enhanced
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 modes, respectively, then you need to use the more general -b option instead of
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 -e, taking one of the following forms:
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109 -b base_baud
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 -b base_baud,spenh_baud
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 -b base_baud,spenh_baud,spenh_max
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 base_baud is the initial baud rate to use for receiving ATR; if no further
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 comma-separated parameters are specified, then this initial baud rate persists
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 for the entire card session without any speed enhancement modes. spenh_baud is
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116 the baud rate to use for F=512 D=8 speed enhancement mode. spenh_max must be
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 1, 2, 4 or 8 (the default is 1); it is the maximum further multiplier that can
b0cf75d0bb2d doc/Serial-SIM-readers article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118 be applied to spenh_baud, if any.