--- a/doc/Sniffer-FPGA-design	Tue Aug 29 22:58:26 2023 +0000
+++ b/doc/Sniffer-FPGA-design	Wed Aug 30 01:09:00 2023 +0000
@@ -1,10 +1,11 @@
-The first version of SIMtrace3 sniffer FPGA (the version in fpga/sniffer-basic,
-no PPS catcher, F/D=372 only for now) has been implemented, tested and proven
-working.  It is an FPGA image for Lattice Icestick, an inexpensive off-the-shelf
-iCE40 FPGA board, and it implements the function of passive sniffing: 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 GSM ME or
-other interface device (ME/ID for short) and a SIM.
+FPGA component of SIMtrace3 sniffer
+===================================
+
+The SIM interface sniffing apparatus of SIMtrace3 consists of a sniffer pod
+(hardware adapter with level shifters) and a Lattice Icestick FPGA board, loaded
+with the appropriate gateware image from the present project.  This document
+describes the design and operation of the FPGA component of this SIMtrace3
+sniffing solution.
 
 Hardware architecture and FPGA design principle
 ===============================================
@@ -15,27 +16,28 @@
 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 is 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) remains unused in this
-application, 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 likewise remain unused.
+sniffer that does not actively participate in the protocol), the FPGA forwards
+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 is the sole functional output from this FPGA, aside from some
+non-essential LED outputs: right now the green LED shows the current state of
+SIM RST line, and we might add another LED showing if SIM CLK is running or
+stopped.  The other UART data line going the opposite direction (output from
+FT2232H) remains unused in this application, 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 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
+bytes are transferred from the FPGA to the host computer; more generally, the
+FPGA can 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.
+byte of an expected pair) during prolonged pauses.  The FPGA transmits 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
@@ -48,7 +50,7 @@
   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
+- additional flags indicating actions 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
@@ -64,7 +66,7 @@
 
 Treating the two transmitted bytes as a single 16-bit word, with the least
 significant 8 bits transmitted first (matching the transmission order of bits
-within a byte), the 16 bits of this word are assigned as follows:
+within a byte, see IEN 137), the 16 bits of this word are assigned as follows:
 
 Bit 15: set to 0 if this message signals ISO 7816-3 character reception or 1 if
 it signals a change of state in the RST line.
@@ -72,9 +74,17 @@
 Bit 14: new state of RST in the case of RST state change messages; should always
 be 1 in character Rx messages.
 
-Bits [13:11]: currently unused and set to 0.
+The remaining bits are valid only in character Rx messages:
+
+Bit 13: set to 0 if this character was captured in F/D=372 mode or 1 if it was
+captured in one of the supported speed enhancement modes (F=512, D=8/16/32/64).
 
-The remaining bits are valid only in character Rx messages:
+Bit 12: set to 1 in the byte position that is expected to be the final PCK byte
+of the card's PPS response in the case of supported speed enhancement modes,
+0 otherwise.
+
+Bit 11: set to 1 in the byte position that is expected to be the PPS1 byte of
+the card's PPS response, 0 otherwise.
 
 Bit 10: set to 1 if the error signal of ISO 7816-3 section 7.3 was detected,
 0 otherwise.
@@ -114,7 +124,7 @@
 The FPGA on the Icestick board receives a 12 MHz clock input.  Our original
 plan was to use the FPGA's on-chip PLL to multiply this clock by 4, producing a
 48 MHz system clock - however, this plan has been shelved for now, and our
-current sniffer-basic design uses the 12 MHz clock directly as its system clock.
+current sniffer design uses the 12 MHz clock directly as its system clock.
 
 The 3 inputs to the FPGA coming from the SIM electrical sniffer (buffered and
 level-shifted SIM RST, CLK and I/O lines) pass through two cascaded DFFs,
@@ -131,20 +141,36 @@
 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
+Our ISO 7816-3 receiver triggers 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
+starts 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 needs to know how many SIM CLK cycles constitute 0.5 etu,
-1 etu and 1.5 etu, in order to locate various needed sampling points relative
-to the instant at which SIM_IO was initially sampled low.
+between SIM CLK and SIM I/O transitions.)
+
+Our ISO 7816-3 receiver needs to know how many SIM CLK cycles constitute one
+etu - or more precisely, our sniffing receiver needs to know how many SIM CLK
+cycles constitute 0.5 etu, 1 etu and 1.5 etu, in order to locate various needed
+sampling points relative to the instant at which SIM_IO was initially sampled
+low.  Our sniffer-pps FPGA supports the following combinations:
 
-The initial version of our sniffer gateware (the version in fpga/sniffer-basic)
-omits the PPS catcher block, hence the just-described etu durations are
-currently fixed to F/D=372 default values.
+F=372, D=1: 372 clocks per etu
+F=512, D=8: 64 clocks per etu
+F=512, D=16: 32 clocks per etu
+F=512, D=32: 16 clocks per etu
+F=512, D=64: 8 clocks per etu
+
+Our sniffing Rx is held down in reset (won't receive anything) while SIM RST is
+low; as we come out of reset upon SIM RST line going high, our sniffing Rx is in
+F/D=372 mode and the PPS catcher state machine is set to its initial state.  As
+ISO 7816-3 characters captured in this F/D=372 mode are received, our PPS
+catcher state machine follows the spec-defined structure of ATR to locate its
+end.  If the end of ATR is followed by a PPS request which is then followed by
+a PPS response, and if the PPS response from the card includes a PPS1 byte that
+invokes one of our supported speed enhancement modes listed above, the sniffing
+receiver's notion of etu length is switched at the correct point in time:
+immediately after finishing RX of the PCK byte that concludes the card's PPS
+response.
 
 Direct and inverse coding conventions
 =====================================
@@ -161,16 +187,29 @@
 Integrated PPS catcher
 ======================
 
-The logic described so far and implemented in the sniffer-basic version will be
-sufficient to capture all exchanges on the SIM interface between ME/ID 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 ME/ID-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.
+Our sniffer FPGA logic was developed incrementally.  The first version,
+preserved in fpga/sniffer-basic in case we ever need to revisit it, uses an ISO
+7816-3 sniffing Rx block with fixed F/D ratio of 372.  That simple version is
+sufficient for sniffing exchanges between a GSM ME and a SIM *if* the etu-
+defining F/D ratio is never switched from the basic default of 372, either
+because the SIM does not support speed enhancement or because the ME does not
+support such.  However, such no-speed-enhancement scenarios are rare:
+
+* All commercial operators' SIMs in the present era do support speed
+  enhancement, and so do our own FCSIM1 cards.  More specifically, our FCSIM1
+  model supports F=512 D=8, while most commercial operators' SIMs that have
+  passed through Mother's hands (plus sysmoUSIM-SJS1 and sysmoISIM-SJA2)
+  support F=512 D=32.
+
+* F=512 D=8 is a speed enhancement mode endorsed by the most classic GSM 11.11
+  spec, and it is supported by classic GSM ME implementations including our dear
+  Calypso.
+
+As a result of the above two factors, most real-life GSM ME to SIM sessions
+which we will need to sniff and trace in the course of Vintage Mobile Phone
+debugging and support will include a PPS exchange switching from F/D=372 to a
+smaller number of SIM CLK cycles per etu, specifically one of F=512 D=8/16/32/64
+modes.
 
 The main difficulty with capturing SIM interface sessions that use speed
 enhancement is as follows: in order for the session capture to be complete,
@@ -181,50 +220,26 @@
 host software to decode all byte exchanges up to this point (ATR from the SIM,
 PPS request from ME/ID, then PPS response) and command the FPGA (UART in the
 other direction, or a modem control line) to switch the etu counters (the
-0.5 etu, 1 etu and 1.5 etu counters mentioned above), we stand very little
-chance of getting this command to the FPGA in time, before ME/ID 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.
+0.5 etu, 1 etu and 1.5 etu counters mentioned earlier in this document), we
+stand very little chance of getting this command to the FPGA in time, before
+ME/ID starts transmitting its next command to the SIM using the new etu
+definition.
 
-* 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.
+Designs that incorporate a local CPU core immediately adjacent to the ISO 7816-3
+receiver block, such as original Osmocom SIMtrace in which the local CPU core
+and the ISO 7816-3 receiver sit in the same AT91SAMx chip, don't suffer from
+this problem: with a local (dedicated, embedded) CPU so close, the firmware can
+react and intervene in time.  However, in the case of our SIMtrace3, the nearest
+CPU is the host computer separated by UART and USB links - not closely coupled
+enough to provide the degree of real-time response that is needed here.  Someone
+could say that we should stick a soft CPU core with firmware into our FPGA - but
+we've implemented a different solution: we have a specialized PPS catcher state
+machine instead.  This gateware FSM follows the spec-defined structure of ATR,
+PPS request and PPS response, and locates the two key items of interest to us:
 
-* Upon receiving that last PCK byte after all prior bytes following the expected
-  protocol, effect the etu counter 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.
+* The PPS1 byte in the card's PPS response, which we check for a supported speed
+  enhancement mode (the upper 6 bits need to match 0x94) and from which we
+  extract the two lsbs selecting among D=8/16/32/64;
 
-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 omits this block altogether, and we will get the rest of the
-system working for ME/ID-to-SIM sessions that stick with F/D=372 - a good test
-configuration would be to use a FreeCalypso GSM ME, 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.
+* The PCK byte that concludes the card's PPS response - the point where we throw
+  the switch to sniffing with the new F/D ratio.