--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/PPS-catcher-FSM	Tue Aug 22 08:55:33 2023 +0000
@@ -0,0 +1,102 @@
+This document describes the PPS catcher state machine (to be implemented in the
+sniffer FPGA) in verbal pseudocode.
+
+INITIAL:
+
+This state will be entered upon reset (held in this state while RST is low).
+Must receive 8'h3B to proceed to state T0, otherwise transition to DONE.
+
+ATR_T0:
+
+Whatever byte we receive in this state, we latch the upper nibble in the Y
+register and the lower nibble in the K register - then proceed to TAn.
+
+ATR_TAn:
+
+Advance to TBn if Y register indicates no TAn OR we got a byte.
+
+ATR_TBn:
+
+Advance to TCn if Y register indicates no TBn OR we got a byte.
+
+ATR_TCn:
+
+Advance to TDn if Y register indicates no TCn OR we got a byte.
+
+ATR_TDn:
+
+If Y register indicates no TDn, advance to state ATR_HIST.
+
+ ELSE wait for byte; upon byte Rx, do the following:
+
+- latch the upper nibble in the Y register;
+- if lower nibble != 0, set TCK present flag;
+- always go back to TAn.
+
+ATR_HIST:
+
+If K == 0, advance to state ATR_TCK.
+
+ ELSE wait for byte; upon byte Rx, decrement K and remain in this state.
+
+ATR_TCK:
+
+Advance to READY_FOR_PPS if Have_TCK flag is false OR we got a byte.
+
+READY_FOR_PPS:
+
+Wait for Rx byte.  If the byte equals 8'hFF, proceed to REQ_PPS0,
+otherwise DONE.
+
+REQ_PPS0:
+
+Wait for Rx byte; latch 3 bits of the received byte and proceed to REQ_PPS1.
+
+REQ_PPS1:
+
+Advance to REQ_PPS2 if register indicates no PPS1 OR we got a byte.
+
+REQ_PPS2:
+
+Advance to REQ_PPS3 if register indicates no PPS2 OR we got a byte.
+
+REQ_PPS3:
+
+Advance to REQ_PCK if register indicates no PPS3 OR we got a byte.
+
+REQ_PCK:
+
+Wait for Rx byte; ignore the received value and go to READY_FOR_RESP.
+
+READY_FOR_RESP:
+
+Wait for Rx byte.  If the byte equals 8'hFF, proceed to RESP_PPS0,
+otherwise DONE.
+
+RESP_PPS0:
+
+Wait for Rx byte.  If PPS1 indicator bit is cleared, go to DONE.  Otherwise,
+latch the 3 bits like in REQ_PPS0 and proceed to RESP_PPS1.
+
+RESP_PPS1:
+
+Wait for Rx byte.  The upper 6 bits must match 6'b100101 - if mismatch, go to
+DONE.  If the upper bits match, latch the two lsbs - they will be the speed
+enhancement multiplier bits - and proceed to RESP_PPS2.
+
+RESP_PPS2:
+
+Advance to RESP_PPS3 if register indicates no PPS2 OR we got a byte.
+
+RESP_PPS3:
+
+Advance to RESP_PCK if register indicates no PPS3 OR we got a byte.
+
+RESP_PCK:
+
+Wait for Rx byte.  Upon getting this final byte, trigger the speed enhancement
+switch and go to DONE.
+
+DONE:
+
+Final state, nothing more happens.