FreeCalypso > hg > fc-sim-sniff

comparison doc/Sniffer-FPGA-design @ 35:695ca51e1564

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Sniffer-FPGA-design: update for finished work
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 30 Aug 2023 01:09:00 +0000
parents c03a882cc49e
children 1068f9fd41d5
comparison
equal deleted inserted replaced
34:c2fc75655937 35:695ca51e1564
1 The first version of SIMtrace3 sniffer FPGA (the version in fpga/sniffer-basic, 1 FPGA component of SIMtrace3 sniffer
2 no PPS catcher, F/D=372 only for now) has been implemented, tested and proven 2 ===================================
3 working. It is an FPGA image for Lattice Icestick, an inexpensive off-the-shelf 3
4 iCE40 FPGA board, and it implements the function of passive sniffing: receiving 4 The SIM interface sniffing apparatus of SIMtrace3 consists of a sniffer pod
5 level-shifted SIM RST, CLK and I/O signals from the 74LVC4T3144 buffer and 5 (hardware adapter with level shifters) and a Lattice Icestick FPGA board, loaded
6 capturing all exchanges that happen on the SIM interface between a GSM ME or 6 with the appropriate gateware image from the present project. This document
7 other interface device (ME/ID for short) and a SIM. 7 describes the design and operation of the FPGA component of this SIMtrace3
8 sniffing solution.
8 9
9 Hardware architecture and FPGA design principle 10 Hardware architecture and FPGA design principle
10 =============================================== 11 ===============================================
11 12
12 The two principal components of the Icestick board are an iCE40HX1K FPGA and an 13 The two principal components of the Icestick board are an iCE40HX1K FPGA and an
13 FT2232H-based USB host interface. Our sniffer logic function in the FPGA 14 FT2232H-based USB host interface. Our sniffer logic function in the FPGA
14 operates principally as a byte forwarder from the ISO 7816-3 sniffer block to 15 operates principally as a byte forwarder from the ISO 7816-3 sniffer block to
15 the FT2232H UART: every time the bus sniffer block captures a character (in ISO 16 the FT2232H UART: every time the bus sniffer block captures a character (in ISO
16 7816-3 terminology) being passed on the SIM electrical interface in either 17 7816-3 terminology) being passed on the SIM electrical interface in either
17 direction (the two directions of transmission are indistinguishable to a tap 18 direction (the two directions of transmission are indistinguishable to a tap
18 sniffer that does not actively participate in the protocol), the FPGA will 19 sniffer that does not actively participate in the protocol), the FPGA forwards
19 forward this character to the connected host computer (by way of FT2232H UART) 20 this character to the connected host computer (by way of FT2232H UART) for
20 for further processing in software. The UART data line going from the FPGA to 21 further processing in software. The UART data line going from the FPGA to the
21 the FT2232H is the sole functional output from this FPGA, beyond debug outputs 22 FT2232H is the sole functional output from this FPGA, aside from some
22 being added during logic development and troubleshooting. The other UART data 23 non-essential LED outputs: right now the green LED shows the current state of
23 line going the opposite direction (output from FT2232H) remains unused in this 24 SIM RST line, and we might add another LED showing if SIM CLK is running or
24 application, i.e., the host software application will only read/receive from the 25 stopped. The other UART data line going the opposite direction (output from
25 ttyUSBx FPGA device and won't send anything to it. All modem control lines on 26 FT2232H) remains unused in this application, i.e., the host software application
26 this UART interface likewise remain unused. 27 will only read/receive from the ttyUSBx FPGA device and won't send anything to
28 it. All modem control lines on this UART interface likewise remain unused.
27 29
28 Serial interface format 30 Serial interface format
29 ======================= 31 =======================
30 32
31 For every ISO 7816-3 character captured by the sniffer, two back-to-back UART 33 For every ISO 7816-3 character captured by the sniffer, two back-to-back UART
32 bytes will be transferred from the FPGA to the host computer; more generally, 34 bytes are transferred from the FPGA to the host computer; more generally, the
33 the FPGA will only transmit pairs of back-to-back bytes on this UART and no 35 FPGA can only transmit pairs of back-to-back bytes on this UART and no
34 singletons or other arrangements - thus the host receiver can always recover 36 singletons or other arrangements - thus the host receiver can always recover
35 synchronization by dropping any partially received two-byte message (the first 37 synchronization by dropping any partially received two-byte message (the first
36 byte of an expected pair) during prolonged pauses. The FPGA will transmit the 38 byte of an expected pair) during prolonged pauses. The FPGA transmits the two
37 two back-to-back UART bytes as a single shift-out of 20 bits, conveying two 39 back-to-back UART bytes as a single shift-out of 20 bits, conveying two bytes
38 bytes in 8N1 framing. 40 in 8N1 framing.
39 41
40 Why are we turning every captured ISO 7816-3 character into a pair of bytes on 42 Why are we turning every captured ISO 7816-3 character into a pair of bytes on
41 our internal UART interface, why not simply forward it as a single byte? The 43 our internal UART interface, why not simply forward it as a single byte? The
42 reason is that we need to pass some additional bits beyond the 8 that comprise 44 reason is that we need to pass some additional bits beyond the 8 that comprise
43 the ISO 7816-3 character payload; the additional bits which we need to pass are 45 the ISO 7816-3 character payload; the additional bits which we need to pass are
46 - the received parity bit; 48 - the received parity bit;
47 - a flag indicating whether or not an error signal (ISO 7816-3 section 7.3) 49 - a flag indicating whether or not an error signal (ISO 7816-3 section 7.3)
48 was seen; 50 was seen;
49 - additional flag bits communicating SIM RST assertion and negation events, 51 - additional flag bits communicating SIM RST assertion and negation events,
50 as distinct from ISO 7816-3 characters; 52 as distinct from ISO 7816-3 characters;
51 - an additional flag indicating an action of the integrated PPS catcher state 53 - additional flags indicating actions of the integrated PPS catcher state
52 machine, to be described later in this document. 54 machine, to be described later in this document.
53 55
54 Assertion or negation of SIM RST is the only other possible event (besides ISO 56 Assertion or negation of SIM RST is the only other possible event (besides ISO
55 7816-3 character capture, with or without attendant PPS catcher state machine 57 7816-3 character capture, with or without attendant PPS catcher state machine
56 action) that can cause the FPGA to send a byte-pair UART message to the host 58 action) that can cause the FPGA to send a byte-pair UART message to the host
62 Detailed serial interface format 64 Detailed serial interface format
63 -------------------------------- 65 --------------------------------
64 66
65 Treating the two transmitted bytes as a single 16-bit word, with the least 67 Treating the two transmitted bytes as a single 16-bit word, with the least
66 significant 8 bits transmitted first (matching the transmission order of bits 68 significant 8 bits transmitted first (matching the transmission order of bits
67 within a byte), the 16 bits of this word are assigned as follows: 69 within a byte, see IEN 137), the 16 bits of this word are assigned as follows:
68 70
69 Bit 15: set to 0 if this message signals ISO 7816-3 character reception or 1 if 71 Bit 15: set to 0 if this message signals ISO 7816-3 character reception or 1 if
70 it signals a change of state in the RST line. 72 it signals a change of state in the RST line.
71 73
72 Bit 14: new state of RST in the case of RST state change messages; should always 74 Bit 14: new state of RST in the case of RST state change messages; should always
73 be 1 in character Rx messages. 75 be 1 in character Rx messages.
74 76
75 Bits [13:11]: currently unused and set to 0.
76
77 The remaining bits are valid only in character Rx messages: 77 The remaining bits are valid only in character Rx messages:
78
79 Bit 13: set to 0 if this character was captured in F/D=372 mode or 1 if it was
80 captured in one of the supported speed enhancement modes (F=512, D=8/16/32/64).
81
82 Bit 12: set to 1 in the byte position that is expected to be the final PCK byte
83 of the card's PPS response in the case of supported speed enhancement modes,
84 0 otherwise.
85
86 Bit 11: set to 1 in the byte position that is expected to be the PPS1 byte of
87 the card's PPS response, 0 otherwise.
78 88
79 Bit 10: set to 1 if the error signal of ISO 7816-3 section 7.3 was detected, 89 Bit 10: set to 1 if the error signal of ISO 7816-3 section 7.3 was detected,
80 0 otherwise. 90 0 otherwise.
81 91
82 Bit 9: sampled line value at the midpoint of the start bit, should be 0 in a 92 Bit 9: sampled line value at the midpoint of the start bit, should be 0 in a
112 =============== 122 ===============
113 123
114 The FPGA on the Icestick board receives a 12 MHz clock input. Our original 124 The FPGA on the Icestick board receives a 12 MHz clock input. Our original
115 plan was to use the FPGA's on-chip PLL to multiply this clock by 4, producing a 125 plan was to use the FPGA's on-chip PLL to multiply this clock by 4, producing a
116 48 MHz system clock - however, this plan has been shelved for now, and our 126 48 MHz system clock - however, this plan has been shelved for now, and our
117 current sniffer-basic design uses the 12 MHz clock directly as its system clock. 127 current sniffer design uses the 12 MHz clock directly as its system clock.
118 128
119 The 3 inputs to the FPGA coming from the SIM electrical sniffer (buffered and 129 The 3 inputs to the FPGA coming from the SIM electrical sniffer (buffered and
120 level-shifted SIM RST, CLK and I/O lines) pass through two cascaded DFFs, 130 level-shifted SIM RST, CLK and I/O lines) pass through two cascaded DFFs,
121 bringing them into our internal clock domain. The delay added by these cascaded 131 bringing them into our internal clock domain. The delay added by these cascaded
122 DFFs is not a concern: we are a passive sniffer without any output back to the 132 DFFs is not a concern: we are a passive sniffer without any output back to the
129 48 MHz SYSCLK. 139 48 MHz SYSCLK.
130 140
131 ISO 7816-3 sniffer block 141 ISO 7816-3 sniffer block
132 ======================== 142 ========================
133 143
134 Our ISO 7816-3 receiver will trigger on the falling edge of the I/O line. Once 144 Our ISO 7816-3 receiver triggers on the falling edge of the I/O line. Once it
135 it detects a high-to-low transition on the SYSCLK-synchronized SIM_IO input, it 145 detects a high-to-low transition on the SYSCLK-synchronized SIM_IO input, it
136 will start counting SIM CLK cycles - we are arbitrarily choosing low-to-high 146 starts counting SIM CLK cycles - we are arbitrarily choosing low-to-high
137 transition of SYSCLK-synchronized SIM_CLK input as the trigger point. (This 147 transition of SYSCLK-synchronized SIM_CLK input as the trigger point. (This
138 choice is arbitrary because per the spec there is no defined phase relation 148 choice is arbitrary because per the spec there is no defined phase relation
139 between SIM CLK and SIM I/O transitions.) Our ISO 7816-3 receiver will need to 149 between SIM CLK and SIM I/O transitions.)
140 know how many SIM CLK cycles constitute one etu - or more precisely, our 150
141 sniffing receiver needs to know how many SIM CLK cycles constitute 0.5 etu, 151 Our ISO 7816-3 receiver needs to know how many SIM CLK cycles constitute one
142 1 etu and 1.5 etu, in order to locate various needed sampling points relative 152 etu - or more precisely, our sniffing receiver needs to know how many SIM CLK
143 to the instant at which SIM_IO was initially sampled low. 153 cycles constitute 0.5 etu, 1 etu and 1.5 etu, in order to locate various needed
144 154 sampling points relative to the instant at which SIM_IO was initially sampled
145 The initial version of our sniffer gateware (the version in fpga/sniffer-basic) 155 low. Our sniffer-pps FPGA supports the following combinations:
146 omits the PPS catcher block, hence the just-described etu durations are 156
147 currently fixed to F/D=372 default values. 157 F=372, D=1: 372 clocks per etu
158 F=512, D=8: 64 clocks per etu
159 F=512, D=16: 32 clocks per etu
160 F=512, D=32: 16 clocks per etu
161 F=512, D=64: 8 clocks per etu
162
163 Our sniffing Rx is held down in reset (won't receive anything) while SIM RST is
164 low; as we come out of reset upon SIM RST line going high, our sniffing Rx is in
165 F/D=372 mode and the PPS catcher state machine is set to its initial state. As
166 ISO 7816-3 characters captured in this F/D=372 mode are received, our PPS
167 catcher state machine follows the spec-defined structure of ATR to locate its
168 end. If the end of ATR is followed by a PPS request which is then followed by
169 a PPS response, and if the PPS response from the card includes a PPS1 byte that
170 invokes one of our supported speed enhancement modes listed above, the sniffing
171 receiver's notion of etu length is switched at the correct point in time:
172 immediately after finishing RX of the PCK byte that concludes the card's PPS
173 response.
148 174
149 Direct and inverse coding conventions 175 Direct and inverse coding conventions
150 ===================================== 176 =====================================
151 177
152 Only the card and not the interface device (ISO 7816-3 terminology) determines 178 Only the card and not the interface device (ISO 7816-3 terminology) determines
159 message as-is, without inverting or reordering them. 185 message as-is, without inverting or reordering them.
160 186
161 Integrated PPS catcher 187 Integrated PPS catcher
162 ====================== 188 ======================
163 189
164 The logic described so far and implemented in the sniffer-basic version will be 190 Our sniffer FPGA logic was developed incrementally. The first version,
165 sufficient to capture all exchanges on the SIM interface between ME/ID and a SIM 191 preserved in fpga/sniffer-basic in case we ever need to revisit it, uses an ISO
166 *if* the etu-defining F/D ratio is never switched from the basic default of 372. 192 7816-3 sniffing Rx block with fixed F/D ratio of 372. That simple version is
167 However, given that most SIM cards of interest to us (our own FCSIM1, as well as 193 sufficient for sniffing exchanges between a GSM ME and a SIM *if* the etu-
168 SIMs issued by various commercial operators) support Fi=512 Di=8 or higher, and 194 defining F/D ratio is never switched from the basic default of 372, either
169 given that even very classic implementations of GSM ME (including our dear 195 because the SIM does not support speed enhancement or because the ME does not
170 Calypso) support this F=512 D=8 speed enhancement mode endorsed by GSM 11.11 196 support such. However, such no-speed-enhancement scenarios are rare:
171 spec, many real-life ME/ID-to-SIM sessions (which we would like to sniff and 197
172 trace) will include a PPS exchange switching to a smaller number of SIM CLK 198 * All commercial operators' SIMs in the present era do support speed
173 cycles per etu. 199 enhancement, and so do our own FCSIM1 cards. More specifically, our FCSIM1
200 model supports F=512 D=8, while most commercial operators' SIMs that have
201 passed through Mother's hands (plus sysmoUSIM-SJS1 and sysmoISIM-SJA2)
202 support F=512 D=32.
203
204 * F=512 D=8 is a speed enhancement mode endorsed by the most classic GSM 11.11
205 spec, and it is supported by classic GSM ME implementations including our dear
206 Calypso.
207
208 As a result of the above two factors, most real-life GSM ME to SIM sessions
209 which we will need to sniff and trace in the course of Vintage Mobile Phone
210 debugging and support will include a PPS exchange switching from F/D=372 to a
211 smaller number of SIM CLK cycles per etu, specifically one of F=512 D=8/16/32/64
212 modes.
174 213
175 The main difficulty with capturing SIM interface sessions that use speed 214 The main difficulty with capturing SIM interface sessions that use speed
176 enhancement is as follows: in order for the session capture to be complete, 215 enhancement is as follows: in order for the session capture to be complete,
177 without any lost bits, the sniffing receiver's knowledge of how many SIM CLK 216 without any lost bits, the sniffing receiver's knowledge of how many SIM CLK
178 cycles constitute an etu needs to change to the new value at exactly the 217 cycles constitute an etu needs to change to the new value at exactly the
179 correct moment in time, which is the moment immediately after the last byte 218 correct moment in time, which is the moment immediately after the last byte
180 (PCK) of the SIM's PPS response passes across the wire. If we were to rely on 219 (PCK) of the SIM's PPS response passes across the wire. If we were to rely on
181 host software to decode all byte exchanges up to this point (ATR from the SIM, 220 host software to decode all byte exchanges up to this point (ATR from the SIM,
182 PPS request from ME/ID, then PPS response) and command the FPGA (UART in the 221 PPS request from ME/ID, then PPS response) and command the FPGA (UART in the
183 other direction, or a modem control line) to switch the etu counters (the 222 other direction, or a modem control line) to switch the etu counters (the
184 0.5 etu, 1 etu and 1.5 etu counters mentioned above), we stand very little 223 0.5 etu, 1 etu and 1.5 etu counters mentioned earlier in this document), we
185 chance of getting this command to the FPGA in time, before ME/ID starts 224 stand very little chance of getting this command to the FPGA in time, before
186 transmitting its next command to the SIM using the new etu definition. 225 ME/ID starts transmitting its next command to the SIM using the new etu
187 226 definition.
188 The Mother's proposed solution is to embed a PPS catcher state machine in the 227
189 sniffer FPGA. This state machine will be set to its initial state upon the 228 Designs that incorporate a local CPU core immediately adjacent to the ISO 7816-3
190 session-opening low-to-high transition on the RST line, and it will look at 229 receiver block, such as original Osmocom SIMtrace in which the local CPU core
191 every ISO 7816-3 character received by the sniffer. The machine will need to 230 and the ISO 7816-3 receiver sit in the same AT91SAMx chip, don't suffer from
192 step through the following states between this starting point and the final 231 this problem: with a local (dedicated, embedded) CPU so close, the firmware can
193 action of changing the half-etu count register: 232 react and intervene in time. However, in the case of our SIMtrace3, the nearest
194 233 CPU is the host computer separated by UART and USB links - not closely coupled
195 * As the ATR bytes are transferred, the state machine will need to understand 234 enough to provide the degree of real-time response that is needed here. Someone
196 enough of ATR format to know which byte constitutes the end of ATR. A fatal 235 could say that we should stick a soft CPU core with firmware into our FPGA - but
197 error in ATR real-time parsing (if the first byte is anything other than 236 we've implemented a different solution: we have a specialized PPS catcher state
198 8'h3B) will put the machine into its inactive state for the remainder of the 237 machine instead. This gateware FSM follows the spec-defined structure of ATR,
199 session until next reset. 238 PPS request and PPS response, and locates the two key items of interest to us:
200 239
201 * If the byte following ATR is 8'hFF, the machine will proceed into PPS request 240 * The PPS1 byte in the card's PPS response, which we check for a supported speed
202 real-time parsing state. If this byte equals any other value, go to the 241 enhancement mode (the upper 6 bits need to match 0x94) and from which we
203 inactive state for the remainder of the session. 242 extract the two lsbs selecting among D=8/16/32/64;
204 243
205 * In the PPS request real-time parsing series of states, the state machine will 244 * The PCK byte that concludes the card's PPS response - the point where we throw
206 need to catch the PPS0 byte and based on this byte, figure out how many bytes 245 the switch to sniffing with the new F/D ratio.
207 it needs to skip.
208
209 * Following the PPS request, the machine will need to real-time-parse the PPS
210 response. Any invalid conditions will take it to the inactive state; however,
211 if the PPS exchange is valid, the machine will need to capture the PPS1 byte
212 and then step through states until the final PCK byte of the PPS response.
213
214 * Upon receiving that last PCK byte after all prior bytes following the expected
215 protocol, effect the etu counter change. Either way, the inactive state is
216 entered at this point, and the state machine will take no further action for
217 the remainder of the session.
218
219 This state machine is of course going to be very complicated, as evident from
220 the functional requirements listed above. The first version of SIMtrace-ice
221 sniffer FPGA omits this block altogether, and we will get the rest of the
222 system working for ME/ID-to-SIM sessions that stick with F/D=372 - a good test
223 configuration would be to use a FreeCalypso GSM ME, with SIM speed enhancement
224 disabled via AT@SPENH=0. Then we shall embark on implementing this proposed
225 PPS catcher state machine.
226
227 The addition of this PPS catcher state machine may increase the complexity of
228 our logic beyond the capacity of the iCE40HX1K FPGA on the Icestick board. If
229 we run into this problem, we'll have to look for a board with a bigger FPGA -
230 but we'll try to fit into the Icestick first.