initial commit: figuring out SPI on the Tang Primer 20K, already 3 devlogs, will commit on a per-devlog/document change basis

devlog/2025-05-04-Stalling.md

@@ -0,0 +1,55 @@
+# SPI slave implementation on the Tang Primer 20K
+Date: 2025-05-04
+
+## Goals and expectations
+Since yesterday I completed the simulated runs for the simple SPI
+slave's logic, so I wanted to test it out on real hardware to get my
+hands dirty, and also try to start adding queues to the logic to
+actually start handling traffic and if the timing allows, play around
+with UART for a while.
+
+## Results
+Less than appealing, definitely room for improvement.  I got stuck
+because apparently the `sclk` pin should be connected to a
+timing-specific pin if I want to treat the incoming signal as a clock
+signal.  That turned today into a huge digging into the documentation
+for the FPGA for usable pins.  And usable `GCLK` pins were hard to
+find since I'm using the dock ext. board and it already repurposed
+several (most) of them to onboard peripheral ports like Ethernet.  I
+have exactly 1 pair of `GCLK` pins, for potentially eight connected
+RPi's.  That's not enough.
+
+So, I'm going with the other method: we're using an internal
+(higher-frequency) clock to capture `sclk` using 2FF synchronizers.
+This would come in handy when I start managing different queues for
+multiple connections, so today isn't completely stalling.
+
+At the very least I got some research done on how the pins on the FPGA
+are purposed, it's been a great learning experience.
+
+So, in a word, I did nothing tangible today, but paved the path for
+tomorrow.
+
+## Reflections
+1. Get things into action, real action.  Sims can only detect logical
+   errors, but throwing the code into Place and Route and letting the
+   FPGA-specific tools warn you about the what you're doing wrong is
+   essential when building this close to actual hardware.
+   - If yesterday opened my mind to simultaneously running logic, then
+     today would be me tripping over because I left the safe embrace
+     of abstracting away the hardware.
+2. More knowledge isn't always bad for the project, need more
+   foresight from now on.
+	 
+## Final Thoughts
+When you port your code from one Linux machine to another, you'd
+expect it to work with some minor tweaks to the dependencies
+(unless they touch the kernel), but porting FPGA code from a sim
+bed to hardware feels harder than writing the logic itself (on an
+unfamiliar platform).
+
+The future is still looking great.
+
+## The next step
+Same as yesterday, test the logic with hardware, try setting up
+buffers, potentially tinker with UART.