\chapter[Modules and toolchain]{Modules, ports and toolchain}
\label{ch:appmod}

\section{List of RTL modules}
\begin{tabularx}{\textwidth}{L{3.4cm} C{2.0cm} Y}
\toprule
\rowh \thd{File} & \thd{Type} & \thd{Role} \\
\midrule
\code{rtl/mac\_unit.v} & combinational & single multiply-accumulator \\
\rowa \code{rtl/mac8.v} & combinational & parallel MAC + balanced adder tree \\
\code{rtl/neuron\_parallel.v} & FSM & neuron: groups, bias, activation, saturation \\
\rowa \code{rtl/layer.v} & structural & N\_NEURONS neurons in parallel \\
\code{rtl/neuron\_memory.v} & FSM & memory/neuron bridge, neuron loop \\
\rowa \code{rtl/layer\_sequencer.v} & FSM & multi-layer sequencing, ping-pong \\
\code{rtl/int8\_memory\_access.v} & FSM & byte $\leftrightarrow$ word conversion \\
\rowa \code{rtl/memory\_interface.v} & FSM & req/ready handshake \\
\code{rtl/psram\_controller.v} & FSM & async 70~ns physical PSRAM bus \\
\rowa \code{rtl/mem\_arbiter.v} & arbiter & 3 ports, priority B$>$C$>$A \\
\code{rtl/spi\_slave.v} & FSM & SPI Mode 0 physical layer + CDC \\
\rowa \code{rtl/spi\_engine.v} & FSM & opcode + register bank \\
\code{rtl/act\_buffer.v} & block RAM & DP16KD activation buffer (Type \#2) \\
\rowa \code{rtl/graph\_engine.v} & FSM & graph-network engine (Type \#2) \\
\code{rtl/spi\_neuron\_top.v} & top & full integration \\
\rowa \code{rtl/memory\_model.v} & model & behavioral RAM (sim) \\
\bottomrule
\end{tabularx}

\section{Ports of the top-level \texttt{spi\_neuron\_top}}
See the complete signal-by-signal table in ch.~\ref{ch:hw}. In summary: clock and reset
(\code{clk}, \code{rst}); application SPI (\code{sclk}, \code{mosi}, \code{miso},
\code{cs\_n}); PSRAM bus (\code{psram\_a[22:0]}, \code{psram\_dq[15:0]},
\code{psram\_ce\_n/oe\_n/we\_n/lb\_n/ub\_n/zz\_n}).

\section{Toolchain}
\begin{tabularx}{\textwidth}{L{3.6cm} L{3.4cm} Y}
\toprule
\rowh \thd{Tool} & \thd{Version} & \thd{Use} \\
\midrule
Yosys & 0.68+post & RTL synthesis $\to$ JSON netlist, ECP5 mapping \\
\rowa nextpnr-ecp5 & 0.11.1-19-g8dbcee5 & placement, routing, timing \\
Project Trellis & install & \code{ecppack}/\code{ecppll}/\code{ecpbram} \\
\rowa Icarus Verilog & \code{-g2012} & functional simulation \\
\bottomrule
\end{tabularx}

\subsection{Main nextpnr parameters}
\begin{lstlisting}[language=,basicstyle=\ttfamily\scriptsize]
--45k                        selects LFE5U-45F
--package CABGA381           package
--speed 8                    speed grade -8
--json <netlist>            netlist from Yosys
--lpf <constraints>         pin constraints (currently empty)
--lpf-allow-unconstrained    allows unconstrained I/Os (benchmark)
--freq 80                    80 MHz timing target
\end{lstlisting}

\subsection{Simulation example}
\begin{lstlisting}[language=,basicstyle=\ttfamily\scriptsize]
iverilog -g2012 -Ptb.PARALLEL=16 -o sim/parametric_256x4_p16 \
  sim/parametric_tb.v rtl/mac_unit.v rtl/mac8.v \
  rtl/neuron_parallel.v rtl/layer.v
vvp sim/parametric_256x4_p16
\end{lstlisting}

\section{Main testbenches}
\begin{tabularx}{\textwidth}{L{5.4cm} Y}
\toprule
\rowh \thd{Testbench} & \thd{Coverage} \\
\midrule
\code{parametric\_tb.v} & 256$\times$4 datapath, accumulate/bias/ReLU/saturation cases \\
\rowa \code{parameter\_sweep\_tb.v} & sweep of valid configurations \\
\code{neuron\_parallel\_tb.v} & activations, runtime width (T7) \\
\rowa \code{neuron\_memory\_tb.v} / \code{\_multi\_tb.v} & single/multi-neuron memory integration, real PSRAM (T5) \\
\code{psram\_controller\_tb.v} & PSRAM controller \\
\rowa \code{psram\_page\_mode\_tb.v} & page bursts, page crossing, close on WRITE/$t_{CEM}$ timeout, byte-enable changes (§~5.5) \\
\code{spi\_slave\_tb.v} & SPI physical layer (4 tests) \\
\rowa \code{spi\_engine\_tb.v} & opcodes, registers (10+ tests) \\
\code{spi\_neuron\_top\_tb.v} & end-to-end, real PSRAM over simulated SPI \\
\rowa \code{spi\_neuron\_top\_runnetwork\_tb.v} & RUN\_NETWORK 2-layer end-to-end \\
\code{layer\_sequencer\_tb.v} & 2-layer sequence, ping-pong, byte-exact copy \\
\bottomrule
\end{tabularx}

\vfill
\begin{center}
\begin{tikzpicture}
\node[draw=fnRule,rounded corners=3pt,inner sep=8pt,fill=fnLight,text width=15.5cm]{
\footnotesize\color{fnGrey}
This datasheet is generated from the RTL code, the documentation and the benchmarks
present in the repository \texttt{github.com/manvalan/FPGA-Neural} as of \datasheetdate.
The Fmax, resource usage and throughput values are those reported in the repository
measurements (real \texttt{.lpf} already assigned and place\&route-verified,
ch.~\ref{ch:hw}) and must be re-verified on any substantial RTL change or as the
Phase~7 timing closure, still in progress, continues (ch.~\ref{ch:roadmap}).};
\end{tikzpicture}
\end{center}