FreeCalypso > hg > fc-sim-sniff
changeset 4:b275c69c1b80
doc: describe proposed FPGA design
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sat, 29 Jul 2023 07:06:54 +0000 |
parents | 0c321f1ce085 |
children | 07c5aac6e84f |
files | doc/DUS-terminology doc/Sniffer-FPGA-design |
diffstat | 2 files changed, 198 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/DUS-terminology Sat Jul 29 07:06:54 2023 +0000 @@ -0,0 +1,7 @@ +Throughout SIMtrace-ice documentation we shall use the term DUS to mean Device +Under Study. The purpose of SIMtrace is to study (or test) the behavior of GSM +phone handsets, modems and other phone-type devices (GSM ME) from the viewpoint +angle of their SIM interface, hence the GSM ME or other SIM-interfacing device +used in a SIMtrace setup is best thought of as the device under study. Using +our acronym DUS throughout this body of documentation gives us the precision +needed in this project.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Sniffer-FPGA-design Sat Jul 29 07:06:54 2023 +0000 @@ -0,0 +1,191 @@ +The first FPGA gateware function to be implemented in the SIMtrace-ice project +is the passive sniffer: receiving level-shifted SIM RST, CLK and I/O signals +from the 74LVC4T3144 buffer and capturing all exchanges that happen on the SIM +interface between a DUS and a SIM. + +The sniffer FPGA logic function will be implemented on the inexpensive off-the- +shelf Icestick board, featuring an iCE40HX1K FPGA and an FT2232H-based USB host +interface. This FPGA logic function will operate principally as a byte +forwarder from the ISO 7816-3 sniffer block to the FT2232H UART: every time the +bus sniffer block captures a character (in ISO 7816-3 terminology) being passed +on the SIM electrical interface in either direction (the two directions of +transmission are indistinguishable to a tap sniffer that does not actively +participate in the protocol), the FPGA will forward this character to the +connected host computer (by way of FT2232H UART) for further processing in +software. The UART data line going from the FPGA to the FT2232H will be the +sole functional output from this FPGA, beyond debug outputs being added during +logic development and troubleshooting. The other UART data line going the +opposite direction (output from FT2232H) will remain unused, i.e., the host +software application will only read/receive from the ttyUSBx FPGA device and +won't send anything to it. All modem control lines on this UART interface will +likewise remain unused. + +Serial interface format +======================= + +For every ISO 7816-3 character captured by the sniffer, two back-to-back UART +bytes will be transferred from the FPGA to the host computer; more generally, +the FPGA will only transmit pairs of back-to-back bytes on this UART and no +singletons or other arrangements - thus the host receiver can always recover +synchronization by dropping any partially received two-byte message (the first +byte of an expected pair) during prolonged pauses. The FPGA will transmit the +two back-to-back UART bytes as a single shift-out of 20 bits, conveying two +bytes in 8N1 framing. + +Why are we turning every captured ISO 7816-3 character into a pair of bytes on +our internal UART interface, why not simply forward it as a single byte? The +reason is that we need to pass some additional bits beyond the 8 that comprise +the ISO 7816-3 character payload; the additional bits which we need to pass are +as follows: + +- the received parity bit; +- a flag indicating whether or not an error signal (ISO 7816-3 section 7.3) + was seen; +- additional flag bits communicating SIM RST assertion and negation events, + as distinct from ISO 7816-3 characters; +- an additional flag indicating an action of the integrated PPS catcher state + machine, to be described later in this document. + +Assertion or negation of SIM RST is the only other possible event (besides ISO +7816-3 character capture, with or without attendant PPS catcher state machine +action) that can cause the FPGA to send a byte-pair UART message to the host +computer. One bit in the 16-bit message will distinguish between characters +and RST events, another bit will indicate the state of RST at the time of the +event (new RST for transitions, 1 for characters), and all other bits are +meaningful only for characters. + +Clocking design +=============== + +The FPGA on the Icestick board receives a 12 MHz clock input; the on-chip PLL +will be used to multiply this clock by 4, producing a 48 MHz system clock. +This 48 MHz SYSCLK will be used for the entirety of the present logic design - +a single-clock fully synchronous design is the best current practice. + +The 3 inputs to the FPGA coming from the SIM electrical sniffer (buffered and +level-shifted SIM RST, CLK and I/O lines) will pass through two cascaded DFFs, +bringing them into our internal clock domain. The delay added by these cascaded +DFFs is not a concern: we are a passive sniffer without any output back to the +SIM interface, and all 3 signal inputs will be subject to the same delay. + +The baud rate on the UART interface between the FPGA and the FT2232H converter +will be 3000000 bps. The UART output block in the FPGA will use a simple /16 +divider from SYSCLK to time its output bits; future derivative designs that will +use the UART interface bidirectionally (such as the planned card emulator FPGA +design) will use SYSCLK directly as the 16x clock for UART reception. This +high (and very non-RS232-standard) UART baud rate was chosen for the following +reasons: + +* Our UART interface is totally private, going nowhere but the on-board FT2232H, + thus it doesn't matter if the baud rate is standard-ish or totally + non-standard. + +* No cables of any kind are used, instead the UART interface is confined to + short PCB traces running between the FPGA and the FTDI chip on the same board + - hence high baud rates are not a problem. + +* Our UART baud rate needs to be high enough to provide good margin, despite + our 2x expansion, at the highest possible effective bps rate on the SIM + interface, meaning the highest possible SIM CLK frequency and the most + aggressive F/D ratio. The combination of SIM CLK at 5 MHz, F=512 and D=64 + corresponds to 625000 bps effective on the SIM interface; running our UART at + 3 Mbps provides sufficient margin. + +ISO 7816-3 sniffer block +======================== + +Our ISO 7816-3 receiver will trigger on the falling edge of the I/O line. Once +it detects a high-to-low transition on the SYSCLK-synchronized SIM_IO input, it +will start counting SIM CLK cycles - we are arbitrarily choosing low-to-high +transition of SYSCLK-synchronized SIM_CLK input as the trigger point. (This +choice is arbitrary because per the spec there is no defined phase relation +between SIM CLK and SIM I/O transitions.) Our ISO 7816-3 receiver will need to +know how many SIM CLK cycles constitute one etu - or more precisely, our +sniffing receiver will operate in half-etu counts, as we need to measure 0.5 etu +to get from the initial falling edge on the I/O line to the mid-etu data +sampling point. Following the session-opening low-to-high transition on the RST +line, our half-etu register will be set to 8'd186, corresponding to F/D=372. +Our PPS catcher state machine will then overwrite this register with a smaller +value based on the captured PPS exchange. + +Direct and inverse coding conventions +===================================== + +Only the card and not the DUS (interface device in ISO 7816-3 terminology) +determines which coding convention is used, direct or inverse. So far we +(FreeCalypso) have not yet encountered a real-life SIM that uses the inverse +convention, only the direct convention kind. In the sniffer function of +SIMtrace-ice, we are going to keep our FPGA gateware simple in this regard and +punt all inverse convention handling to the software application on the host +computer: the FPGA will pass the 9 received bits (8 data bits and 1 parity bit) +to the 16-bit UART message as-is, without inverting or reordering them. + +Integrated PPS catcher +====================== + +The logic described so far will be sufficient to capture all exchanges on the +SIM interface between a DUS and a SIM *if* the etu-defining F/D ratio is never +switched from the basic default of 372. However, given that most SIM cards of +interest to us (our own FCSIM1, as well as SIMs issued by various commercial +operators) support Fi=512 Di=8 or higher, and given that even very classic +implementations of GSM ME (including our dear Calypso) support this F=512 D=8 +speed enhancement mode endorsed by GSM 11.11 spec, many real-life DUS-to-SIM +sessions (which we would like to sniff and trace) will include a PPS exchange +switching to a smaller number of SIM CLK cycles per etu. + +The main difficulty with capturing SIM interface sessions that use speed +enhancement is as follows: in order for the session capture to be complete, +without any lost bits, the sniffing receiver's knowledge of how many SIM CLK +cycles constitute a half-etu needs to change to the new value at exactly the +correct moment in time, which is the moment immediately after the last byte +(PCK) of the SIM's PPS response passes across the wire. If we were to rely on +host software to decode all byte exchanges up to this point (ATR from the SIM, +PPS request from the DUS, then PPS response) and command the FPGA (UART in the +other direction, or a modem control line) to switch the half-etu counter, we +stand very little chance of getting this command to the FPGA in time, before +the DUS starts transmitting its next command to the SIM using the new etu +definition. + +The Mother's proposed solution is to embed a PPS catcher state machine in the +sniffer FPGA. This state machine will be set to its initial state upon the +session-opening low-to-high transition on the RST line, and it will look at +every ISO 7816-3 character received by the sniffer. The machine will need to +step through the following states between this starting point and the final +action of changing the half-etu count register: + +* As the ATR bytes are transferred, the state machine will need to understand + enough of ATR format to know which byte constitutes the end of ATR. A fatal + error in ATR real-time parsing (if the first byte is anything other than + 8'h3B) will put the machine into its inactive state for the remainder of the + session until next reset. + +* If the byte following ATR is 8'hFF, the machine will proceed into PPS request + real-time parsing state. If this byte equals any other value, go to the + inactive state for the remainder of the session. + +* In the PPS request real-time parsing series of states, the state machine will + need to catch the PPS0 byte and based on this byte, figure out how many bytes + it needs to skip. + +* Following the PPS request, the machine will need to real-time-parse the PPS + response. Any invalid conditions will take it to the inactive state; however, + if the PPS exchange is valid, the machine will need to capture the PPS1 byte + and then step through states until the final PCK byte of the PPS response. + +* Upon receiving that last PCK byte after all prior bytes following the expected + protocol, effect the half-etu count change. Either way, the inactive state + is entered at this point, and the state machine will take no further action + for the remainder of the session. + +This state machine is of course going to be very complicated, as evident from +the functional requirements listed above. The first version of SIMtrace-ice +sniffer FPGA will omit this block altogether, and we will get the rest of the +system working for DUS-to-SIM sessions that stick with F/D=372 - a good test +configuration would be to use a FreeCalypso GSM ME as DUS, with SIM speed +enhancement disabled via AT@SPENH=0. Then we shall embark on implementing this +proposed PPS catcher state machine. + +The addition of this PPS catcher state machine may increase the complexity of +our logic beyond the capacity of the iCE40HX1K FPGA on the Icestick board. If +we run into this problem, we'll have to look for a board with a bigger FPGA - +but we'll try to fit into the Icestick first.