--- a/doc/Sniffer-FPGA-design	Mon Aug 21 03:09:34 2023 +0000
+++ b/doc/Sniffer-FPGA-design	Mon Aug 21 06:50:55 2023 +0000
@@ -1,24 +1,32 @@
-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 first FPGA logic function in the SIMtrace-ice project has been implemented
+and is now waiting to be tested: it is the basic sniffer FPGA in the
+fpga/sniffer-basic directory.  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.
+
+This FPGA gateware function is currently waiting to be tested: some custom
+hardware needs to be assembled before the FPGA can be tested.  The PCB fab order
+for our mv-sniffer adapter board has just been placed; we will need to receive
+the PCB, get it populated, and also populate the missing pin headers on the
+Icestick board before we can test our FPGA.
 
-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.
+The two principal components of the Icestick board are an iCE40HX1K FPGA and an
+FT2232H-based USB host interface.  Our sniffer logic function in the FPGA
+operates 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 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.
 
 Serial interface format
 =======================
@@ -54,27 +62,39 @@
 event (new RST for transitions, 1 for characters), and all other bits are
 meaningful only for characters.
 
-Clocking design
-===============
+Detailed serial interface format
+--------------------------------
+
+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:
+
+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.
+
+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 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 remaining bits are valid only in character Rx messages:
+
+Bit 10: set to 1 if the error signal of ISO 7816-3 section 7.3 was detected,
+0 otherwise.
 
-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.
+Bit 9: sampled line value at the midpoint of the start bit, should be 0 in a
+properly working system.
+
+Bit 8: received parity bit;
+
+Bits [7:0]: payload bits of the received character.
+
+UART baud rate
+==============
 
 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:
+is 3000000 bps.  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
@@ -91,6 +111,26 @@
   corresponds to 625000 bps effective on the SIM interface; running our UART at
   3 Mbps provides sufficient margin.
 
+Clocking design
+===============
+
+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.
+
+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,
+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.
+
+As stated in the previous section, the baud rate on the UART interface between
+the FPGA and the FT2232H converter is 3000000 bps.  The UART output block in
+the FPGA uses a simple /4 divider from CLK12 (board-level 12 MHz clock input)
+to time its output bits; the original intent was to use a /16 divider from
+48 MHz SYSCLK.
+
 ISO 7816-3 sniffer block
 ========================
 
@@ -101,50 +141,52 @@
 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.
+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.
+
+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.
 
 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.
+Only the card and not the interface device (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
+passes 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 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.
 
 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
+cycles constitute an 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.
+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
@@ -173,17 +215,17 @@
   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.
+  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.
 
 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.
+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