--- /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.