fix typo

To close #67.

Co-authored-by: sb10q <sb@m-labs.hk>
Reviewed-on: sinara-hw/datasheets#72
Co-authored-by: architeuthis <am@m-labs.hk>
Co-committed-by: architeuthis <am@m-labs.hk>

1106.tex

@@ -0,0 +1,97 @@
+\input{preamble.tex}
+\graphicspath{{images/1106}, {images}}
+
+\title{1106 EEM AC Power Module}
+\author{M-Labs Limited}
+\date{January 2025}
+\revision{Revision 1}
+\companylogo{\includegraphics[height=0.73in]{artiq_sinara.pdf}}
+
+\begin{document}
+\maketitle
+
+\section{Features}
+
+    \begin{itemize}
+        \item{Front panel IEC inlet}
+        \item{80-264V input range}
+        \item{Five 4-pin Molex MiniFit outputs}
+        \item{EMC filter}
+    \end{itemize}
+
+\section{Applications}
+
+    \begin{itemize}
+        \item{Power supply for ARTIQ/Sinara systems}
+        \item{Provides 400W at 25CFM cooling, 200W with free air convection}
+    \end{itemize}
+
+\section{General Description}
+
+    The 1106 EEM AC Power Module is a 8hp EEM form factor module, part of the ARTIQ/Sinara family. It serves as an in-crate power supply to other Sinara cards such as 1124 Carrier Kasli 2.0 and 1125 Carrier Kasli-SoC.
+
+    The AC Power Module features universal IEC input in the front panel and five 4-pin Molex output, directly compatible with Kasli Carriers, at the very rear side of the module. The mains circuit is protected by a steel cover.
+
+% Switch to next column
+\vfill\break
+
+%\begin{figure}[h]
+%    \centering
+%    \scalebox{1.15}{
+%    \begin{circuitikz}[european, every label/.append style={align=center}]
+%        \begin{scope}[]
+%            % if applicable
+%        \end{scope}
+%    \end{circuitikz}
+%    }
+
+%    \caption{Simplified Block Diagram}
+%\end{figure}
+
+\begin{figure}[hbt!]
+    \centering
+    \includegraphics[height=2.5in]{photo1106.jpg}
+    \caption{EEM AC Power Module with handle}
+    \includegraphics[height=2.5in, angle=90]{fp1106.pdf}
+    \caption{EEM AC Power Module front panel}
+\end{figure}
+
+% For wide tables, a single column layout is better. It can be switched
+% page-by-page.
+\onecolumn
+
+\sourcesection{1106 EEM AC Power Module}{https://github.com/sinara-hw/EEM_PWR_MOD_AC}
+
+\section{Electrical Specifications}
+
+Specifications of parameters are based on the datasheet of the EPP-400-12 power supply\footnote{\url{https://www.meanwell.com/upload/pdf/EPP-400/EPP-400-SPEC.PDF}}.
+
+\begin{table}[h]
+\centering
+\begin{threeparttable}
+\caption{Electrical Specifications}
+\begin{tabularx}{0.75\textwidth}{l | c c c | c | X}
+    \thickhline
+    \textbf{Parameter} & \textbf{Min} & \textbf{Typ.} & \textbf{Max} & \textbf{Unit} & \textbf{Conditions} \\
+    \hline
+    Output voltage & & 12 & & V & \\ \hline
+    \multirow{2}{*}{Rated current} & & 33.3 & & \multirow{2}{*}{A} & 25CFM forced cooling \\ \cline{2-4}
+        & & 20.8 & & & Convection \\ \hline
+    \multirow{2}{*}{Rated power} & & 399.6 & & \multirow{2}{*}{W} & 25CFM forced cooling \\ \cline{2-4}
+        & & 249.6 & & & Convection \\ \hline
+    Input voltage           & 80 & & 264    & VAC & \\ \hline
+    Input frequency range   & 47 & & 63     & Hz  & \\ \hline
+    \thickhline
+\end{tabularx}
+\end{threeparttable}
+\end{table}
+
+\section{Indicator LEDs}
+
+The 1106 EEM AC Power Module features several indicator LEDs. Four serve as current indicators signaling 25\%, 50\%, 75\% and 100\% load. \texttt{12V} LED signals power on. Additional \texttt{OVERTEMP} LED signals overtemp or overload.
+
+\ordersection{1106 EEM AC Power Module}
+
+\finalfootnote
+
+\end{document}

1124.tex

@@ -1,4 +1,5 @@
-\include{preamble.tex}
+\input{preamble.tex}
+\input{shared/coredevice.tex}
 \graphicspath{{images/1124}{images}}
 
 \title{1124 Carrier Kasli 2.0}
@@ -13,28 +14,28 @@
 \section{Features}
 
 \begin{itemize}
-\item{4 SFP 6Gb/s slots for Ethernet and DRTIO}
-\item{12 EEM ports for daughtercards}
-\item{4 MMCX clock outputs}
-\item{Xilinx Artix-7 FPGA core}
-\item{DDR3 SDRAM}
+    \item{4 SFP 6Gb/s slots for Ethernet \& DRTIO at 2.5Gb/s}
+    \item{12 EEM ports for daughtercards}
+    \item{4 MMCX clock outputs}
+    \item{Xilinx Artix-7 FPGA core}
+    \item{DDR3 SDRAM}
 \end{itemize}
 
 \section{Applications}
 
 \begin{itemize}
-\item{Run ARTIQ kernels}
-\item{Communicate with the host}
-\item{Control other Sinara EEM cards}
-\item{Distributed Real-Time I/O}
+    \item{Run ARTIQ kernels}
+    \item{Communicate with the host}
+    \item{Control other Sinara EEM cards}
+    \item{Distributed Real-Time I/O}
 \end{itemize}
 
 \section{General Description}
-The 1124 Kasli 2.0 Carrier card is an 8hp EEM module, designed to run ARTIQ kernels sent from a host machine over the network. It supports up to 12 EEM connections to other EEM cards in the ARTIQ-Sinara family and up four SFP connections, used for comunications with other carriers and/or Ethernet.
+    The 1124 Kasli 2.0 Carrier card is an 8hp EEM module, designed to run ARTIQ kernels sent from a host machine over the network. It supports up to 12 EEM connections to other EEM cards in the ARTIQ/Sinara family and up four SFP connections, used for comunications with other carriers and/or Ethernet.
 
-Real-time control of EEM daughtercards is implemented using the ARTIQ RTIO system. 1ns temporal resolution can be achieved for TTL events.
+    Real-time control of EEM daughtercards is implemented using the ARTIQ RTIO system. 1ns temporal resolution can be achieved for TTL events.
 
-4 SFP 6Gb/s slots are provided. One may be used for Ethernet, which supports communication with a host machine. Remaining slots can be used by the ARTIQ Distributed Real-Time Input/Output (DRTIO) system, which allows for the use of additional core devices (e.g. Kasli 2.0, Kasli-SoC) as satellite cards, capable of running subkernels or distributing commands from the \mbox{DRTIO} master.
+    4 SFP 6Gb/s slots are provided. One may be used for Ethernet, which supports communication with a host machine. Remaining slots can be used by the ARTIQ Distributed Real-Time Input/Output (DRTIO) system, which allows for the use of additional core devices (e.g. Kasli 2.0, Kasli-SoC) as satellite cards, capable of running subkernels or distributing commands from the \mbox{DRTIO} master.
 
 % Switch to next column
 \vfill\break
@@ -163,142 +164,74 @@ Real-time control of EEM daughtercards is implemented using the ARTIQ RTIO syste
     \caption{Kasli 2.0 front panel}
 \end{figure}
 
-% For wide tables, a single column layout is better. It can be switched
-% page-by-page.
+% END PAGE ONE (for wide pages a single-column layout is preferable)
+
 \onecolumn
 
 \sourcesection{Kasli 2.0}{https://github.com/sinara-hw/Kasli}
 
 \section{Electrical Specifications}
-External clock parameters are derived based on the internal termination specified in
-UG471\footnote{\label{ug471}\url{https://docs.xilinx.com/v/u/en-US/ug471\_7Series\_SelectIO}}
-and the voltage range specified in
-DS181\footnote{\label{ds181}\url{https://docs.xilinx.com/v/u/en-US/ds181\_Artix\_7\_Data\_Sheet}}. These figures account for the insertion loss of the RF transformer (TC2-1TX+\footnote{\label{rf_trans}\url{https://www.minicircuits.com/pdfs/TC2-1TX+.pdf}}).
-\begin{table}[h]
-\centering
-\begin{threeparttable}
-\caption{Recommended Operating Conditions}
-\begin{tabularx}{0.85\textwidth}{l | c c c | c | X}
-    \thickhline
-    \textbf{Parameter} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
-    \textbf{Unit} & \textbf{Conditions} \\
-    \hline
-    Clock input & & & & &\\
-    \hspace{3mm} Input frequency & & 125 & & MHz & Si5324 synthesizer bypassed \\
-    \cline{2-6}
-    % 100R termination & 100/350/600 mV differential input after the transformer.
-    & \multicolumn{3}   {c|}{10/100/125} & MHz & RTIO clock synthesized from input \\
-    \cline{2-6}
-    \hspace{3mm} Power & -9 & 1.5 & 5.5 & dBm & \\
-    \hline
-    Power supply rating & \multicolumn{4}{c|}{12V, 5A} & \\
-    \thickhline
-\end{tabularx}
-\end{threeparttable}
-\end{table}
 
-Power is to be supplied through the barrel connector in the front panel, size 5.5 mm OD, 2.5 mm ID, and is passed on to daughtercards through the EEM connections. Locking barrel connectors are supported.
+    External clock parameters are derived based on the internal termination specified in
+    UG471\footnote{\label{ug471}\url{https://docs.amd.com/v/u/en-US/ug471_7Series_SelectIO}}
+    and the voltage range specified in
+    DS181\footnote{\label{ds181}\url{https://docs.xilinx.com/v/u/en-US/ds181\_Artix\_7\_Data\_Sheet}}. These figures account for the insertion loss of the RF transformer (TC2-1TX+\footnote{\label{rf_trans}\url{https://www.minicircuits.com/pdfs/TC2-1TX+.pdf}}).
+
+    \spectable
 
 \section{FPGA}
 
-Kasli 2.0 features an XC7A100T-3FGG484E Xilinx Artix-7 FPGA to facilitate reconfigurable high-speed real-time control of inputs and outputs. Most commonly, this FPGA is flashed with binaries compiled from the ARTIQ (Advanced Real-Time Infrastructure for Quantum physics) control system, which equips the carrier board with specialized gateware for handling other Sinara EEMs and an on-FPGA CPU for running ARTIQ experiment \mbox{kernels}.
+    Kasli 2.0 features an XC7A100T-3FGG484E Xilinx Artix-7 FPGA to facilitate reconfigurable high-speed real-time control of inputs and outputs. Most commonly, this FPGA is flashed with binaries compiled from the ARTIQ (Advanced Real-Time Infrastructure for Quantum physics) control system, which equips the carrier board with specialized gateware for handling other Sinara EEMs and an on-FPGA CPU for running ARTIQ experiment \mbox{kernels}.
 
-ARTIQ is open-source and can be found in the repository \url{https://github.com/m-labs/artiq}. Orders of Sinara hardware are normally accompanied with precompiled binaries. Long-term support for ARTIQ systems can also be purchased.
+    A micro-USB located on the front panel is equipped for JTAG, I2C, and UART serial output. The serial interface runs at 115200bps 8-N-1.
 
-A micro-USB located on the front panel is equipped for JTAG, I2C, and UART serial output. The serial interface runs at 115200bps 8-N-1.
+\artiqsection
 
-\subsection{Note on distributed RTIO (DRTIO)}
-
-DRTIO is the time and data transfer system that allows ARTIQ RTIO channels to be distributed among several core device carrier boards, synchronized and controlled by a central core device. The system itself is more fully described in the ARTIQ documentation\footnote{\label{manual-drtio}\url{https://m-labs.hk/artiq/manual/drtio.html}}. With ARTIQ firmware/gateware, supported core devices, including Kasli 2.0, can take one of three roles:
-\begin{enumerate}
-    \item \textbf{Master} \\
-    The DRTIO master is unique in a DRTIO system. It requires a direct network connection to the host machine. It may make downstream connections to satellites. It controls its own local RTIO channels and the downstream DRTIO satellite(s).
-    \item \textbf{Satellite} \\
-    Any other core devices in a DRTIO system are DRTIO satellites. They require an upstream connection to one other core device, master or satellite, through which communications will ultimately be chained to the master. They may make further downstream connections to other satellites. They may control RTIO channels through subkernels or simply pass on communications from the master.
-    \item \textbf{Standalone}\\
-    When run in a non-distributed ARTIQ configuration, with a single central core device but no satellites, that core device is instead known as standalone.
-\end{enumerate}
+    \noteondrtio{Kasli 2.0}
 
 \section{Communication Interfaces}
 
-Communication between devices is implemented using 1000Base-T small form-factor pluggable (SFP) interfaces. Four are available on the Kasli 2.0. Appropriate SFP transceivers must be plugged inside the corresponding SFP cages. Each SFP connector possesses an indicator LED.
+    Communication between devices is implemented using 1000Base-T small form-factor pluggable (SFP) interfaces. Four are available on the Kasli 2.0. Appropriate SFP transceivers must be plugged inside the corresponding SFP cages. Each SFP connector possesses an indicator LED.
 
-\subsection{Upstream connection}
+    Transceiver maximum speed is 6.6 Gb/s\footnote{\url{https://www.amd.com/en/products/adaptive-socs-and-fpgas/technologies/high-speed-serial.html}}. DRTIO is normally run at 2.5 Gb/s with 8b10b encoding.
 
-A Kasli 2.0 board must acquire an upstream connection through the \texttt{SFP0} slot.
+    \subsection{Upstream connection}
 
-\begin{itemize}
-    \item \textbf{Standalone/Master} \\
-    An Ethernet-capable SFP transceiver should be inserted into the \texttt{SFP0} slot. Typically, a 10000Base-X RJ45 SFP module is used, with an network-connected Ethernet cable attached to the module.
-    \item \textbf{Satellite} \\
-    The \texttt{SFP0} port should be connected to one of the free SFP slots on an upstream core device, using a cable connection with SFP transceivers.
-\end{itemize}
+    A Kasli 2.0 board must acquire an upstream connection through the \texttt{SFP0} slot.
 
-\subsection{Downstream connection}
-Kasli 2.0 supports up to 3 DRTIO satellite connections per device. Any of the 3 downstream SFP ports (i.e. \texttt{SFP1}, \texttt{SFP2}, \texttt{SFP3}) may be used.
+    \begin{itemize}
+        \item \textbf{Standalone/Master} \\
+        An Ethernet-capable SFP transceiver should be inserted into the \texttt{SFP0} slot. Typically, a 10000Base-X RJ45 SFP module is used, with an network-connected Ethernet cable attached to the module.
+        \item \textbf{Satellite} \\
+        The \texttt{SFP0} port should be connected to one of the free SFP slots on an upstream core device, using a cable or fibre connection with SFP transceivers.
+    \end{itemize}
 
-\section{Clock Routing}
-\subsection{Standalone/Master}
-The RTIO clock is typically synthesized by the Si5324 clock multiplier and distributed by the ADCLK948 clock fanout buffer to both the FPGA and the MMCX connectors. Alternatively, an external reference can be supplied through the front panel SMA connector. It is then buffered in the FPGA and sent to the Si5324 for clock synthesis. Kasli 2.0 supports a set of RTIO clock options:
-\begin{table}[H]
-    \centering
-    \begin{tabular}{|c|c|c|}
-    \hline
-    RTIO frequency           & Configuration          & Clock generation                                                \\ \hline
-    100 MHz                  & \texttt{int\char`_100}               & internal crystal oscillator using PLL, 100 MHz output           \\ \hline
-    \multirow{4}{*}{125 MHz} & \texttt{int\char`_125}               & internal crystal oscillator using PLL, 125 MHz output (default) \\ \cline{2-3}
-                             & \texttt{ext0\char`_synth0\char`_10to125}  & external 10 MHz reference using PLL, 125 MHz output             \\ \cline{2-3}
-                             & \texttt{ext0\char`_synth0\char`_100to125} & external 100 MHz reference using PLL, 125 MHz output            \\ \cline{2-3}
-                             & \texttt{ext0\char`_synth0\char`_125to125} & external 125 MHz reference using PLL, 125 MHz output            \\ \hline
-    150 MHz                  & \texttt{int\char`_150}               & internal crystal oscillator using PLL, 150 MHz output           \\ \hline
-    \end{tabular}
-    \end{table}
+    \subsection{Downstream connection}
+    Kasli 2.0 supports up to 3 DRTIO satellite connections per device. Any of the 3 downstream SFP ports (i.e. \texttt{SFP1}, \texttt{SFP2}, \texttt{SFP3}) may be used. The destination on port \texttt{SFPn} normally receives the destination number \texttt{n}.
 
-The clock synthesizer may also be bypassed, using the \texttt{ext0\char`_bypass} option, which will accept a RTIO clock directly supplied to the SMA connector. The resulting signal is then routed to both the RTIO system and downstream satellites.
-
-Clocking options in a running system should be configured by setting the value of the \texttt{rtio\char`_clock} key to the desired configuration through \texttt{artiq\char`_coremgmt}. For example, a RTIO frequency of 125MHz will be synthesized from an external 10 MHz signal after issuing the following command:
-
-\begin{minted}{bash}
-    artiq_coremgmt config write -s rtio_clock ext0_synth0_10to125
-\end{minted}
-
-and rebooting.
-
-\subsection{Satellite}
-The RTIO clock is recovered from the SFP transceiver connected to the upstream device. The resulting signal is then cleaned up by the Si5324 and routed to both the RTIO system and downstream satellites.
-
-\subsection{WRPLL}
-
-Kasli 2.0 can be configured to use WRPLL, a clock recovery method making use of White Rabbit's DDMTD (Digital Dual Mixer Time Difference) and the card's Si549 oscillators, both to lock the main RTIO clock and to lock satellite clocks to master.
+\clockingsection{Kasli 2.0}{FPGA}
 
 \section{User LEDs}
 
-Kasli 2.0 supplies three user LEDs for debugging purposes. Two are located on the front panel. The third is located on the PCB itself, beside the SFP cage. An additional ERR LED on the front panel is used by ARTIQ firmware to indicate a runtime panic.
+    Kasli 2.0 supplies three user LEDs for debugging purposes. Two are located on the front panel. The third is located on the PCB itself, beside the SFP cage. An additional ERR LED on the front panel is used by ARTIQ firmware to indicate a runtime panic.
 
-\newpage
+\sysdescsection
 
-\codesection{Kasli 2.0 1124 carrier}
+    An example description file for a system using 1124 Kasli 2.0 as a master core device might begin:
 
-\subsection{Direct Memory Access (DMA)}
-Instead of directly emitting RTIO events, sequences of RTIO events can be recorded in advance and stored in the local SDRAM. The event sequence can then be replayed at a specified timestamp. This is of special advantage in cases where RTIO events are too closely placed to be generated as they are executed, as events can be replayed at a higher speed than the on-FPGA CPU alone is capable of.
+    \begin{tcolorbox}[colback=white]
+        \begin{minted}{json}
+            "target": "kasli",
+            "variant": "my_variant",
+            "hw_rev": "v2.0",
+            "base": "master",
+            "peripherals": [    ]
+        \end{minted}
+    \end{tcolorbox}
 
-The following example records an LED event sequence and replays it twice consecutively using \texttt{CoreDMA}. When run, the LED should blink twice.
+    \coresysdesc
 
-\inputcolorboxminted{firstline=10,lastline=29}{examples/dma.py}
-
-Stored waveforms can be referenced and replayed in different kernels, but cannot be retrieved and must be regenerated if the core device is rebooted.
-
-\newpage
-
-\subsection{Dataset manipulation with core device cache}
-Experiments may require values computed or found in previously executed kernels. To avoid invoking an RPC or sacrificing the pre-computation in \texttt{prepare()} stage, data can be stored in the core device cache.
-
-The following code snippets describe two experiments, in which the data from the first experiment is cached. The data is then retrieved and printed in hexadecimal form in the second experiment.
-
-\inputcolorboxminted{firstline=9,lastline=16}{examples/cache.py}
-\inputcolorboxminted{firstline=24,lastline=35}{examples/cache.py}
-
-Similar to DMA, cached data is no longer retrievable once the core device has been rebooted.
+\coredevicecode{Kasli 2.0 1124 carrier}
 
 \ordersection{1124 Carrier Kasli 2.0}
 

1125.tex

@@ -0,0 +1,144 @@
+\input{preamble}
+\input{shared/coredevice}
+\graphicspath{{images/1125}{images}}
+
+\title{1125 Carrier Kasli-SoC}
+\author{M-Labs Limited}
+\date{December 2024}
+\revision{Revision 1} % potentially publishable pending whether block diagram is necessary
+\companylogo{\includegraphics[height=0.73in]{artiq_sinara.pdf}}
+
+\begin{document}
+\maketitle
+
+\section{Features}
+
+\begin{itemize}
+    \item{RJ45 10/100/1000T Ethernet connector}
+    \item{4 SFP 12Gb/s slots for DRTIO at 2.5Gb/s}
+    \item{12 EEM ports for daughtercards}
+    \item{Xilinx Zynq-7000 SoC with Kintex-7 FPGA}
+    \item{SD card flash memory}
+\end{itemize}
+
+\section{Applications}
+
+\begin{itemize}
+    \item{Run ARTIQ kernels}
+    \item{Communicate with the host}
+    \item{Control other Sinara EEM cards}
+    \item{Distributed Real-Time I/O}
+\end{itemize}
+
+\section{General Description}
+
+    The 1125 Kasli-SoC Carrier card is an 8hp EEM module, designed to run ARTIQ-Zynq kernels sent over the network from a host machine. Kasli-SoC is built around a Xilinx Zynq-7000 SoC, capable of running more complex computations at high speed than its sister card 1124 Kasli 2.0. It supports up to 12 EEM connections to other EEM cards in the ARTIQ-Sinara family and up four SFP connections for comunications with other carriers. A dedicated Ethernet port is used for communications with the host.
+
+    Real-time control of EEM daughtercards is implemented using the ARTIQ RTIO system. 1ns temporal resolution can be achieved for TTL events.
+
+    4 SFP 12Gb/s slots are provided. These can be used by the ARTIQ Distributed Real-Time Input/Output (DRTIO) system, which allows for the use of additional core devices (e.g. Kasli or other Kasli-SoCs) as satellite cards, capable of running subkernels or relaying commands to a larger number of peripherals.
+
+% Switch to next column
+\vfill\break
+
+% TODO, possibly: block diagram
+
+\begin{figure}[hbt!]
+    \centering
+    \includegraphics[height=3in]{photo1125.jpg}
+    \caption{Kasli-SoC card}
+    \includegraphics[angle=90,height=1in]{Kasli-SoC_FP.pdf}
+    \caption{Kasli-SoC front panel}
+\end{figure}
+
+% END PAGE ONE (for wide pages a single-column layout is preferable)
+\onecolumn
+
+\sourcesection{Kasli-SoC}{https://github.com/sinara-hw/Kasli-SOC/}
+
+\section{Electrical Specifications}
+
+    External clock parameters are derived based on the internal termination specified in
+    UG471\footnote{\label{ug471}\url{https://docs.amd.com/v/u/en-US/ug471_7Series_SelectIO}}
+    and the voltage range specified in
+    DS191\footnote{\label{ds191}\url{https://docs.amd.com/v/u/en-US/ds191-XC7Z030-XC7Z045-data-sheet}}. These figures account for the insertion loss of the RF transformer (TC2-1TX+\footnote{\label{rf_trans}\url{https://www.minicircuits.com/pdfs/TC2-1TX+.pdf}}).
+
+    \spectable
+
+\section{SoC}
+
+    Kasli-SoC features a XC7Z030-3FFG676E Xilinx Zynq-7000 System-on-Chip with a Kintex-7 FGPA and an Cortex-A9 dual-core processor to facilitate high-speed real-time control of inputs and outputs. The use of the SoC allows for more complex computations at higher speed than Kasli 2.0's purely on-FPGA CPU. Usually, the SoC is flashed with firmware and gateware binaries compiled from the ARTIQ (Advanced Real-Time Infrastructure for Quantum physics) control system, which equips the carrier board with the ability to control other Sinara EEMs and run ARTIQ experiment kernels.
+
+    A micro-USB located on the front panel is equipped for JTAG, I2C, and UART serial output. The serial interface runs at 115200bps 8-N-1.
+
+\artiqsection
+
+    ARTIQ-supported core devices based on Zynq-7000 SoCs, including Kasli-SoC, require firmware and gateware compiled from the ARTIQ-Zynq port, which can be found in the repository \url{https://git.m-labs.hk/M-Labs/artiq-zynq}.
+
+    \noteondrtio{Kasli-SoC}
+
+\section{Communication Interfaces}
+
+    Communication between core devices is implemented with 1000Base-T small form-factor pluggable (SFP) interfaces. Four are available on 1125 Kasli-SoC. Each SFP connector possesses an indicator LED.
+
+    Transceiver maximum speed is 12.5 Gb/s\footnote{\url{https://www.amd.com/en/products/adaptive-socs-and-fpgas/technologies/high-speed-serial.html}}. DRTIO is normally run at 2.5 Gb/s with 8b10b encoding.
+
+    Additionally, a RJ45 10/100/1000T Ethernet port is featured for network connection to a host machine.
+
+    \subsection{Upstream connection}
+
+    \begin{itemize}
+        \item \textbf{Standalone/Master} \\
+        A network-connected Ethernet cable should be attached the front panel Ethernet port to enable communication with a host machine.
+        \item \textbf{Satellite} \\
+        Satellites must acquire an upstream connection to another satellite or the master. The \texttt{SFP0} port should be connected to one of the free SFP slots on an upstream core device, using a cable or fibre connection with SFP transceivers.
+    \end{itemize}
+
+    \subsection{Downstream connection}
+    Kasli-SoC supports up to 4 DRTIO satellite connections per device. Any of the 4 downstream SFP ports (i.e. \texttt{SFP0}, \texttt{SFP1}, \texttt{SFP2}, \texttt{SFP3}) may be freely used. Port \texttt{SFPn} normally receives the destination number \texttt{n + 1}.
+
+\clockingsection{Kasli-SoC}{SoC}
+
+\newpage
+
+\section{Configuring Boot Mode}
+
+    Kasli-SoC is capable of booting either remotely, over JTAG USB, or directly from the SD card. See the ARTIQ manual for more instructions on how to correctly flash and boot a core device. Boot mode must be configured by flipping physical switches on the board. The boot mode DIP switches are located in the middle of the board. To boot from USB, flip both switches towards the label \texttt{JTAG}. To boot from the SD card, flip both switches towards the label \texttt{SD}.
+
+    \begin{figure}[hbt!]
+        \centering
+        \includegraphics[height=3in]{kasli-soc_dip_switches.jpg}
+        \caption{Position of DIP switches, SD card, and reset pins}
+    \end{figure}
+
+    \subsection{POR jumpers and POR reset}
+
+    A known Xilinx hardware bug prevents repeatedly booting over JTAG without a POR reset. If necessary, repeated boots can be made possible by physically setting jumpers on both the \texttt{PS\_POR\_B} and \texttt{PS\_SRST\_B} pins (marked in figure above) and triggering a reset over JTAG, see also the M-Labs POR reset script.\footnote{\url{https://git.m-labs.hk/M-Labs/zynq-rs/src/branch/master/kasli_soc_por.py}}
+
+\section{User LEDs}
+
+    Kasli-SoC designates two user LEDs for debugging purposes. One is located on the PCB; it can be found at the very bottom left of the board, below the SFP cage, labeled \texttt{USER0}. The second is located on the front panel, besides the Ethernet port, labeled \texttt{L1}.
+
+\sysdescsection
+
+    An example description file for a system using 1125 Kasli-SoC as a master core device might begin:
+
+    \begin{tcolorbox}[colback=white]
+        \begin{minted}{json}
+            "target": "kasli_soc",
+            "variant": "my_variant",
+            "hw_rev": "v1.0",
+            "base": "master",
+            "peripherals": [    ]
+        \end{minted}
+    \end{tcolorbox}
+
+    \coresysdesc
+
+\coredevicecode{1125 Kasli-SoC carrier}
+
+\ordersection{1125 Carrier Kasli-SoC}
+
+\finalfootnote
+
+\end{document}

2118-2128.tex

@@ -4,7 +4,7 @@
 \title{2118 BNC-TTL / 2128 SMA-TTL}
 \author{M-Labs Limited}
 \date{January 2022}
-\revision{Revision 2}
+\revision{Revision 3}
 \companylogo{\includegraphics[height=0.73in]{artiq_sinara.pdf}}
 
 \begin{document}
@@ -13,30 +13,30 @@
 \section{Features}
 
 \begin{itemize}
-\item{8 TTL channels}
-\item{Input- and output-capable}
-\item{Galvanically isolated}
-\item{3ns minimum pulse width}
-\item{BNC or SMA connectors}
+    \item{8 TTL channels}
+    \item{Input- and output-capable}
+    \item{Galvanically isolated}
+    \item{3ns minimum pulse width}
+    \item{BNC or SMA connectors}
 \end{itemize}
 
 \section{Applications}
 
 \begin{itemize}
-\item{Photon counting}
-\item{External equipment trigger}
-\item{Optical shutter control}
+    \item{Photon counting}
+    \item{External equipment trigger}
+    \item{Optical shutter control}
 \end{itemize}
 
 \section{General Description}
 
-The 2118 BNC-TTL card is an 8hp EEM module; the 2128 SMA-TTL is a 4hp EEM module. Both TTL cards add general-purpose digital I/O capabilities to carrier cards such as 1124 Kasli and 1125 Kasli-SoC.
+    The 2118 BNC-TTL card is an 8hp EEM module; the 2128 SMA-TTL is a 4hp EEM module. Both TTL cards add general-purpose digital I/O capabilities to carrier cards such as 1124 Kasli and 1125 Kasli-SoC.
 
-Each card provides two banks of four digital channels, for a total of eight digital channels, with respectively either BNC (2118) or SMA (2128) connectors. Each bank possesses individual ground isolation. The direction (input or output) of each bank can be selected using DIP switches, and applies to all four channels of the bank.
+    Each card provides two banks of four digital channels, for a total of eight digital channels, with respectively either BNC (2118) or SMA (2128) connectors. Each bank possesses individual ground isolation. The direction (input or output) of each bank can be selected using DIP switches, and applies to all four channels of the bank.
 
-Each channel supports 50\textOmega~terminations, individually controllable using DIP switches. Outputs tolerate short circuits indefinitely.
+    Each channel supports 50\textOmega~terminations, individually controllable using DIP switches. Outputs tolerate short circuits indefinitely. Both cards are capable of a minimum pulse width of 3ns.
 
-Both cards are capable of a minimum pulse width of 3ns.
+    Isolated TTL cards are not well suited to low-noise or low-jitter applications due to interference from isolation components. For low-noise applications, use non-isolated cards such as 2238 MCX-TTL or 2245 LVDS-TTL.
 
 % Switch to next column
 \vfill\break
@@ -295,11 +295,11 @@ Both cards are capable of a minimum pulse width of 3ns.
 \begin{figure}[hbt!]
     \centering
     \includegraphics[height=1.8in]{photo2118-2128.jpg }
-    \caption{BNC-TTL and SMA-TTL cards}%
-    \includegraphics[angle=90, height=0.7in]{DIO_BNC_FP.jpg}
-    \includegraphics[angle=90, height=0.4in]{DIO_SMA_FP.jpg}
-    \caption{BNC-TTL and SMA-TTL front panels}%
-    \label{fig:example}%
+    \caption{BNC-TTL and SMA-TTL cards}
+    \includegraphics[angle=90, height=0.7in]{fp2118.jpg}
+    \includegraphics[angle=90, height=0.4in]{fp2128.jpg}
+    \caption{BNC-TTL and SMA-TTL front panels}
+    \label{fig:example}
 \end{figure}
 
 \onecolumn
@@ -307,159 +307,185 @@ Both cards are capable of a minimum pulse width of 3ns.
 \sourcesectiond{2118 BNC-TTL}{2128 SMA-TTL}{https://github.com/sinara-hw/DIO_BNC}{https://github.com/sinara-hw/DIO_SMA}
 
 \section{Electrical Specifications}
-All specifications are in $0\degree C \leq T_A \leq 70\degree C$ unless otherwise noted.
-Specifications were derived based on the datasheets of the bus transceiver IC (SN74BCT25245DW\footnote{\label{transceiver}\url{https://www.ti.com/lit/ds/symlink/sn74bct25245.pdf}}) and the isolator IC (SI8651BB-B-IS1\footnote{\label{isolator}\url{https://www.skyworksinc.com/-/media/Skyworks/SL/documents/public/data-sheets/si865x-datasheet.pdf}}). The typical value of minimum pulse width is based on test results\footnote{\label{sinara187}\url{https://github.com/sinara-hw/sinara/issues/187}}.
+    All specifications are in $0\degree C \leq T_A \leq 70\degree C$ unless otherwise noted.
+    Specifications were derived based on the datasheets of the bus transceiver IC (SN74BCT25245DW\footnote{\label{transceiver}\url{https://www.ti.com/lit/ds/symlink/sn74bct25245.pdf}}) and the isolator IC (SI8651BB-B-IS1\footnote{\label{isolator}\url{https://www.skyworksinc.com/-/media/Skyworks/SL/documents/public/data-sheets/si865x-datasheet.pdf}}). The typical value of minimum pulse width is based on test results\footnote{\label{sinara187}\url{https://github.com/sinara-hw/sinara/issues/187}}.
 
-\begin{table}[h]
-\begin{threeparttable}
-\caption{Recommended Operating Conditions}
-\begin{tabularx}{\textwidth}{l | c c c | c | X}
-    \thickhline
-    \textbf{Parameter} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
-    \textbf{Unit} & \textbf{Conditions} \\
-    \hline
-    High-level input voltage\repeatfootnote{transceiver} & 2 & & 5.5* & V & \\
-    \hline
-    Low-level input voltage\repeatfootnote{transceiver} & -0.5 & & 0.8 & V & \\
-    \hline
-    Input clamp current\repeatfootnote{transceiver} & & & -18 & mA & termination disabled \\
-    \hline
-    High-level output current\repeatfootnote{transceiver} & & & -160 & mA & \\
-    \hline
-    Low-level output current\repeatfootnote{transceiver} & & & 376 & mA & \\
-    \thickhline
-    \multicolumn{6}{l}{*With the 50\textOmega~termination enabled, the input voltage should not exceed 5V.}
-\end{tabularx}
-\end{threeparttable}
-\end{table}
+    \begin{table}[h]
+    \begin{threeparttable}
+    \caption{Recommended Operating Conditions}
+    \begin{tabularx}{\textwidth}{l | c c c | c | X}
+        \thickhline
+        \textbf{Parameter} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
+        \textbf{Unit} & \textbf{Conditions} \\
+        \hline
+        High-level input voltage\repeatfootnote{transceiver} & 2 & & 5.5* & V & \\
+        \hline
+        Low-level input voltage\repeatfootnote{transceiver} & -0.5 & & 0.8 & V & \\
+        \hline
+        Input clamp current\repeatfootnote{transceiver} & & & -18 & mA & termination disabled \\
+        \hline
+        High-level output current\repeatfootnote{transceiver} & & & -160 & mA & \\
+        \hline
+        Low-level output current\repeatfootnote{transceiver} & & & 376 & mA & \\
+        \thickhline
+        \multicolumn{6}{l}{*With the 50\textOmega~termination enabled, the input voltage should not exceed 5V.}
+    \end{tabularx}
+    \end{threeparttable}
+    \end{table}
 
-\begin{table}[h]
-\begin{threeparttable}
-\caption{Electrical Characteristics}
-\begin{tabularx}{\textwidth}{l | c c c | c | X}
-    \thickhline
-    \textbf{Parameter} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
-    \textbf{Unit} & \textbf{Conditions} \\
-    \hline
-    High-level output voltage\repeatfootnote{transceiver} & 2 &  &  & V & $I_{OH}$=-160mA \\
-    & 2.7 &  &  & V & $I_{OH}$=-6mA \\
-    \hline
-    Low-level output voltage\repeatfootnote{transceiver} & & 0.42 & 0.55 & V & $I_{OL}$=188mA \\
-    &  &  & 0.7 & V & $I_{OL}$=376mA \\
-    \hline
-    Minimum pulse width\repeatfootnote{isolator}\textsuperscript{,}\repeatfootnote{sinara187} & & 3 & 5 & ns & \\
-    \hline
-    Pulse width distortion\repeatfootnote{isolator} & & 0.2 & 4.5 & ns &  \\
-    \hline
-    Peak jitter\repeatfootnote{isolator} & & 350 & & ps &  \\
-    \hline
-    Data rate\repeatfootnote{isolator} & 0 & & 150 & Mbps & \\
-    \thickhline
-\end{tabularx}
-\end{threeparttable}
-\end{table}
+    \begin{table}[h]
+    \begin{threeparttable}
+    \caption{Electrical Characteristics}
+    \begin{tabularx}{\textwidth}{l | c c c | c | X}
+        \thickhline
+        \textbf{Parameter} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
+        \textbf{Unit} & \textbf{Conditions} \\
+        \hline
+        High-level output voltage\repeatfootnote{transceiver} & 2 &  &  & V & $I_{OH}$=-160mA \\
+        & 2.7 &  &  & V & $I_{OH}$=-6mA \\
+        \hline
+        Low-level output voltage\repeatfootnote{transceiver} & & 0.42 & 0.55 & V & $I_{OL}$=188mA \\
+        &  &  & 0.7 & V & $I_{OL}$=376mA \\
+        \hline
+        Minimum pulse width\repeatfootnote{isolator}\textsuperscript{,}\repeatfootnote{sinara187} & & 3 & 5 & ns & \\
+        \hline
+        Pulse width distortion\repeatfootnote{isolator} & & 0.2 & 4.5 & ns &  \\
+        \hline
+        Peak jitter\repeatfootnote{isolator} & & 350 & & ps &  \\
+        \hline
+        Data rate\repeatfootnote{isolator} & 0 & & 150 & Mbps & \\
+        \thickhline
+    \end{tabularx}
+    \end{threeparttable}
+    \end{table}
 
-Minimum pulse width was measured by generating pulses of progressively longer duration through a DDS generator and using them as input for a BNC-TTL card. The input BNC-TTL card was connected to another BNC-TTL card as output. The output signal is measured and shown in Figure \ref{fig:pulsewidth}.
+    Low-jitter applications should note carefully the jitter introduced by the signal isolator. Noise is also introduced between the primary and secondary domains by the DC/DC converter. Where noise or jitter are crucial, it is instead recommended to use non-isolated cards such as 2238 MCX-TTL or 2245 LVDS-TTL.
 
-\begin{figure}[ht]
-    \centering
-    \includegraphics[height=3in]{bnc_ttl_min_pulse_width.png}
-    \caption{Minimum pulse width required for BNC-TTL card}
-    \label{fig:pulsewidth}
-\end{figure}
+    Minimum pulse width was measured by generating pulses of progressively longer duration through a DDS generator and using them as input for a BNC-TTL card. The input BNC-TTL card was connected to another BNC-TTL card as output. The output signal is measured and shown in Figure \ref{fig:pulsewidth}.
+
+    \begin{figure}[ht]
+        \centering
+        \includegraphics[height=3in]{bnc_ttl_min_pulse_width.png}
+        \caption{Minimum pulse width required for BNC-TTL card}
+        \label{fig:pulsewidth}
+    \end{figure}
 
 \newpage
 
-The red trace shows the DDS generator input pulses. The blue trace shows the measured signal from the output BNC-TTL. Note that the first red pulse failed to reach the 2.1V threshold required by TTL and was not propagated. The first blue (output) pulse is the result of the second red (input) pulse, of 3ns width, which propagated correctly. 
+    The red trace shows the DDS generator input pulses. The blue trace shows the measured signal from the output BNC-TTL. Note that the first red pulse failed to reach the 2.1V threshold required by TTL and was not propagated. The first blue (output) pulse is the result of the second red (input) pulse, of 3ns width, which propagated correctly.
 
 \section{Configuring IO Direction \& Termination}
 
-IO direction and termination must be configured by setting physical switches on the board. The termination switches are found on the middle-left and the IO direction switches on the middle-right of both cards. Termination switches select between high impedance (\texttt{OFF}) and 50\textOmega~(\texttt{ON}). Note that termination switches are by-channel but IO direction switches are by-bank. 
+    IO direction and termination must be configured by setting physical switches on the board. The termination switches are found on the middle-left and the IO direction switches on the middle-right of both cards. Termination switches select between high impedance (\texttt{OFF}) and 50\textOmega~(\texttt{ON}). Note that termination switches are by-channel but IO direction switches are by-bank.
 
-\begin{itemize}
-    \itemsep0em
-    \item IO direction switch closed (\texttt{ON}) \\
-          Fixes the corresponding bank to output. The IO direction cannot be changed by I\textsuperscript{2}C.
-    \item IO direction switch open (OFF) \\
-          The corresponding bank is set to input by default. IO direction \textit{can} be changed by I\textsuperscript{2}C.
-\end{itemize}
+    \begin{itemize}
+        \itemsep0em
+        \item IO direction switch closed (\texttt{ON}) \\
+            Fixes the corresponding bank to output. The IO direction cannot be changed by I\textsuperscript{2}C.
+        \item IO direction switch open (OFF) \\
+            The corresponding bank is set to input by default. IO direction \textit{can} be changed by I\textsuperscript{2}C.
+    \end{itemize}
 
-\begin{figure}[hbt!]
-    \centering
-    \subfloat[\centering BNC-TTL]{{
-        \includegraphics[height=1.5in]{bnc_ttl_switches.jpg}
-    }}%
-    \subfloat[\centering SMA-TTL]{{
-        \includegraphics[height=1.5in]{sma_ttl_switches.jpg}
-    }}%
-    \caption{Position of switches}%
-\end{figure}
+    \begin{figure}[hbt!]
+        \centering
+        \subfloat[\centering BNC-TTL]{{
+            \includegraphics[height=1.5in]{bnc_ttl_switches.jpg}
+        }}%
+        \subfloat[\centering SMA-TTL]{{
+            \includegraphics[height=1.5in]{sma_ttl_switches.jpg}
+        }}%
+        \caption{Position of switches}%
+    \end{figure}
+
+\sysdescsection
+
+    2118 BNC-TTL and 2128 SMA-TTL should be entered in the \texttt{peripherals} list of the corresponding core device in the following format:
+
+    \begin{tcolorbox}[colback=white]
+        \begin{minted}{json}
+            "name" : {
+                "type": "dio",
+                "board": "DIO_BNC", // or "DIO_SMA", optional
+                "ports": [0],
+                "edge_counter": true, // optional
+                "bank_direction_low": "input", // or "output"
+                "bank_direction_high": "output" // or "input"
+            }
+        \end{minted}
+    \end{tcolorbox}
+
+    Replace 0 with the EEM port number used on the core device. Any port can be used. The \texttt{edge\_counter} field is boolean and may be specified true or false; a setting \texttt{true} will make a corresponding ARTIQ \texttt{edge\_counter} module available and consume a corresponding amount of additonal gateware resources. If not included, its default value is false.
 
-\newpage
 \codesection{2118 BNC-TTL/2128 SMA-TTL cards}
 
-Timing accuracy in these examples is well under 1 nanosecond thanks to ARTIQ RTIO infrastructure.
+    Timing accuracy in these examples is well under 1 nanosecond thanks to ARTIQ RTIO infrastructure.
 
-\subsection{One pulse per second}
-The channel should be configured as output in both the gateware and hardware.
-\inputcolorboxminted{firstline=9,lastline=14}{examples/ttl.py}
-
-\subsection{Morse code}
-This example demonstrates some basic algorithmic features of the ARTIQ-Python language.
-\inputcolorboxminted{firstline=22,lastline=39}{examples/ttl.py}
+    \subsection{One pulse per second}
+    The channel should be configured as output in both the gateware and hardware.
+    \inputcolorboxminted{firstline=9,lastline=14}{examples/ttl.py}
 
 \newpage
-\subsection{Sub-coarse-RTIO-cycle pulse}
-With the use of ARTIQ RTIO, only one event can be enqueued per \textit{coarse RTIO cycle}, which typically corresponds to 8ns. To emit pulses of less than 8ns, careful timing is needed to ensure that the \texttt{ttl.on()} \& \texttt{ttl.off()} event are submitted during different coarse RTIO cycles.
 
-\inputcolorboxminted{firstline=60,lastline=64}{examples/ttl.py}
+    \subsection{Morse code}
+    This example demonstrates some basic algorithmic features of the ARTIQ-Python language.
+    \inputcolorboxminted{firstline=22,lastline=39}{examples/ttl.py}
 
-\subsection{Edge counting in a 1ms window}
-The \texttt{TTLInOut} class implements \texttt{gate\char`_rising()}, \texttt{gate\char`_falling()} \& \texttt{gate\char`_both()} for rising edge, falling edge, both rising edge \& falling edge detection respectively.
-The channel should be configured as input in both gateware and hardware. Invoke one of the 3 methods to start edge detection.
-\inputcolorboxminted{firstline=14,lastline=15}{examples/ttl_in.py}
-Input signal can generated from another TTL channel or from other sources. Manipulate the timeline cursor to generate TTL pulses using the same kernel.
-\inputcolorboxminted{firstline=10,lastline=22}{examples/ttl_in.py}
-The detected edges are registered to the RTIO input FIFO. By default, the FIFO can hold 64 events. The FIFO depth is defined by the \texttt{ififo\char`_depth} parameter for \texttt{Channel} class in \texttt{rtio/channel.py}.
-Once the threshold is exceeded, an \texttt{RTIOOverflow} exception will be triggered when the input events are read by the kernel CPU.
-Finally, invoke \texttt{count()} to retrieve the edge count from the input gate.
+    \subsection{Sub-coarse-RTIO-cycle pulse}
+    With the use of ARTIQ RTIO, only one event can be enqueued per \textit{coarse RTIO cycle}, which typically corresponds to 8ns. To emit pulses of less than 8ns, careful timing is needed to ensure that the \texttt{ttl.on()} \& \texttt{ttl.off()} event are submitted during different coarse RTIO cycles.
 
-The RTIO system can report at most one edge detection event for every coarse RTIO cycle. In principle, to guarantee all rising edges are counted (with \texttt{gate\char`_rising()} invoked), the theoretical minimum separation between rising edges is one coarse RTIO cycle (typically 8 ns). However, both the electrical specifications and the possibility of triggering \texttt{RTIOOverflow} exceptions should also be considered.
+    \inputcolorboxminted{firstline=60,lastline=64}{examples/ttl.py}
 
 \newpage
-\subsection{Edge counting using \texttt{EdgeCounter}}
-This example code uses a gateware counter to substitute the software counter, which has a maximum count rate of approximately 1 million events per second. If a gateware counter is enabled on the TTL channel, it can typically count up to 125 million events per second:
-\inputcolorboxminted{firstline=31,lastline=36}{examples/ttl_in.py}
-Edges are detected by comparing the current input state and that of the previous coarse RTIO cycle. Therefore, the theoretical minimum separation between 2 opposite edges is 1 coarse RTIO cycle (typically 8 ns).
 
-\subsection{Responding to an external trigger}
-One channel needs to be configured as input, and the other as output.
-\inputcolorboxminted{firstline=45,lastline=51}{examples/ttl_in.py}
+    \subsection{Edge counting in a 1ms window}
+    The \texttt{TTLInOut} class implements \texttt{gate\char`_rising()}, \texttt{gate\char`_falling()} \& \texttt{gate\char`_both()} for rising edge, falling edge, both rising edge \& falling edge detection respectively.
+    The channel should be configured as input in both gateware and hardware. Invoke one of the 3 methods to start edge detection.
+    \inputcolorboxminted{firstline=14,lastline=15}{examples/ttl_in.py}
+    Input signal can generated from another TTL channel or from other sources. Manipulate the timeline cursor to generate TTL pulses using the same kernel.
 
-\subsection{62.5 MHz clock signal generation}
-A TTL channel can be configured as a \texttt{ClockGen} channel, which generates a periodic clock signal. Each channel has a phase accumulator operating on the RTIO clock, where it is incremented by the frequency tuning word at each coarse RTIO cycle. Therefore, jitter should be expected when the desired frequency cannot be obtained by dividing the coarse RTIO clock frequency with a power of 2.
+    \inputcolorboxminted{firstline=10,lastline=22}{examples/ttl_in.py}
+    The detected edges are registered to the RTIO input FIFO. By default, the FIFO can hold 64 events. The FIFO depth is defined by the \texttt{ififo\char`_depth} parameter for \texttt{Channel} class in \texttt{rtio/channel.py}.
+    Once the threshold is exceeded, an \texttt{RTIOOverflow} exception will be triggered when the input events are read by the kernel CPU.
+    Finally, invoke \texttt{count()} to retrieve the edge count from the input gate.
 
-Typically, with the coarse RTIO clock at 125 MHz, a \texttt{ClockGen} channel can generate up to 62.5 MHz.
-
-\inputcolorboxminted{firstline=72,lastline=75}{examples/ttl.py}
+    The RTIO system can report at most one edge detection event for every coarse RTIO cycle. In principle, to guarantee all rising edges are counted (with \texttt{gate\char`_rising()} invoked), the theoretical minimum separation between rising edges is one coarse RTIO cycle (typically 8 ns). However, both the electrical specifications and the possibility of triggering \texttt{RTIOOverflow} exceptions should also be considered.
 
 \newpage
-\subsection{Minimum sustained event separation}
-The minimum sustained event separation is the least time separation between input gated events for which all gated edges can be continuously \& reliabily timestamped by the RTIO system without causing \texttt{RTIOOverflow} exceptions. The following \texttt{run()} function finds the separation by approximating the time of running \texttt{timestamp\char`_mu()} as a constant. Import the \texttt{time} library to use \texttt{time.sleep()}.
 
-\inputcolorboxminted{firstline=63,lastline=98}{examples/ttl_in.py}
+    \subsection{Edge counting using \texttt{EdgeCounter}}
+    This example code uses a gateware counter to substitute the software counter, which has a maximum count rate of approximately 1 million events per second. If a gateware counter is enabled on the TTL channel, it can typically count up to 125 million events per second:
+    \inputcolorboxminted{firstline=31,lastline=36}{examples/ttl_in.py}
+    Edges are detected by comparing the current input state and that of the previous coarse RTIO cycle. Therefore, the theoretical minimum separation between 2 opposite edges is 1 coarse RTIO cycle (typically 8 ns).
 
-\begin{center}
-\begin{table}[H]
-    \captionof{table}{Minimum sustained event separation of different carriers}
-    \centering
-    \begin{tabular}{|c|c|c|}
-    \hline
-    Carrier  & Kasli v1.1 & Kasli-SoC \\ \hline
-    Duration & 650 ns     & 600 ns    \\ \hline
-    \end{tabular}
-    \end{table}
-\end{center}
+    \subsection{Responding to an external trigger}
+    One channel needs to be configured as input, and the other as output.
+    \inputcolorboxminted{firstline=45,lastline=51}{examples/ttl_in.py}
+
+    \subsection{62.5 MHz clock signal generation}
+    A TTL channel can be configured as a \texttt{ClockGen} channel, which generates a periodic clock signal. Each channel has a phase accumulator operating on the RTIO clock, where it is incremented by the frequency tuning word at each coarse RTIO cycle. Therefore, jitter should be expected when the desired frequency cannot be obtained by dividing the coarse RTIO clock frequency with a power of 2.
+
+    Typically, with the coarse RTIO clock at 125 MHz, a \texttt{ClockGen} channel can generate up to 62.5 MHz.
+
+    \inputcolorboxminted{firstline=72,lastline=75}{examples/ttl.py}
+
+\newpage
+
+    \subsection{Minimum sustained event separation}
+    The minimum sustained event separation is the least time separation between input gated events for which all gated edges can be continuously \& reliabily timestamped by the RTIO system without causing \texttt{RTIOOverflow} exceptions. The following \texttt{run()} function finds the separation by approximating the time of running \texttt{timestamp\char`_mu()} as a constant. Import the \texttt{time} library to use \texttt{time.sleep()}.
+
+    \inputcolorboxminted{firstline=63,lastline=98}{examples/ttl_in.py}
+
+    \begin{center}
+    \begin{table}[H]
+        \captionof{table}{Minimum sustained event separation of different carriers}
+        \centering
+        \begin{tabular}{|c|c|c|}
+        \hline
+        Carrier  & Kasli v1.1 & Kasli-SoC \\ \hline
+        Duration & 650 ns     & 600 ns    \\ \hline
+        \end{tabular}
+        \end{table}
+    \end{center}
 
 \ordersection{2118 BNC-TTL/2128 SMA-TTL}
 

2238.tex

@@ -4,7 +4,7 @@
 \title{2238 MCX-TTL}
 \author{M-Labs Limited}
 \date{January 2022}
-\revision{Revision 2}
+\revision{Revision 3}
 \companylogo{\includegraphics[height=0.73in]{artiq_sinara.pdf}}
 
 \begin{document}
@@ -13,28 +13,28 @@
 \section{Features}
 
 \begin{itemize}
-\item{16 MCX-TTL channels}
-\item{Input and output capable}
-\item{No galvanic isolation}
-\item{High speed and low jitter}
-\item{MCX connectors}
+    \item{16 MCX-TTL channels}
+    \item{Input and output capable}
+    \item{No galvanic isolation}
+    \item{High speed and low jitter}
+    \item{MCX connectors}
 \end{itemize}
 
 \section{Applications}
 
 \begin{itemize}
-\item{Photon counting}
-\item{External equipment trigger}
-\item{Optical shutter control}
+    \item{Photon counting}
+    \item{External equipment trigger}
+    \item{Optical shutter control}
 \end{itemize}
 
 \section{General Description}
 
-The 2238 MCX-TTL card is a 4hp EEM module. It adds general-purpose digital I/O capabilities to carrier cards such as 1124 Kasli and 1125 Kasli-SoC.
+    The 2238 MCX-TTL card is a 4hp EEM module. It adds general-purpose digital I/O capabilities to carrier cards such as 1124 Kasli and 1125 Kasli-SoC.
 
-Each card provides four banks of four digital channels each for a total of sixteen digital channels, with MCX connectors in the front panel, controlled through two EEM connectors. Each individual EEM connector controls two banks independently. Single EEM operation is possible. The direction (input or output) of each bank can be selected using DIP switches, and applies to all four channels of the bank.
+    Each card provides four banks of four digital channels each for a total of sixteen digital channels, with MCX connectors in the front panel, controlled through two EEM connectors. Each individual EEM connector controls two banks independently. Single EEM operation is possible. The direction (input or output) of each bank can be selected using DIP switches, and applies to all four channels of the bank.
 
-Each channel supports 50\textOmega~terminations individually controllable using DIP switches. This card can achieve higher speed and lower jitter than the isolated 2118/2128 BNC/SMA-TTL cards.
+    Each channel supports 50\textOmega~terminations individually controllable using DIP switches. This card can achieve higher speed and lower jitter than the isolated 2118/2128 BNC/SMA-TTL cards.
 
 % Switch to next column
 \vfill\break
@@ -439,7 +439,7 @@ Each channel supports 50\textOmega~terminations individually controllable using
     \centering
     \includegraphics[height=2in]{photo2238.jpg}
     \caption{MCX-TTL card}
-    \includegraphics[angle=90, height=0.6in]{DIO_MCX_FP.pdf}
+    \includegraphics[angle=90, height=0.6in]{fp2238.pdf}
     \caption{MCX-TTL front panel}
 \end{figure}
 
@@ -451,104 +451,142 @@ Each channel supports 50\textOmega~terminations individually controllable using
 
 \section{Electrical Specifications}
 
-All specifications are in $-40\degree C \leq T_A \leq 85\degree C$ unless otherwise noted. Information in this section is based on the datasheet of the bus transceiver IC (74LVT162245MTD\footnote{\label{transceiver}\url{https://www.onsemi.com/pdf/datasheet/74lvt162245-d.pdf}}).
+    All specifications are in $-40\degree C \leq T_A \leq 85\degree C$ unless otherwise noted. Information in this section is based on the datasheet of the bus transceiver IC (74LVT162245MTD\footnote{\label{transceiver}\url{https://www.onsemi.com/pdf/datasheet/74lvt162245-d.pdf}}).
 
-\begin{table}[h]
-\begin{threeparttable}
-\caption{Recommended Operating Conditions}
-\begin{tabularx}{\textwidth}{l | c c c | c | X}
-    \thickhline
-    \textbf{Parameter} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
-    \textbf{Unit} & \textbf{Conditions} \\
-    \hline
-    Input voltage & 0 & & 5.5* & V \\
-    \hline
-    High-level output current & & & -24 & mA \\
-    \hline
-    Low-level output current & & & 24 & mA \\
-    \hline
-    Input edge rate & & & 10 & ns/V & $0.8V \leq V_I \leq 2.0V$ \\
-    \thickhline
-    \multicolumn{6}{l}{*With the 50\textOmega~termination enabled, the input voltage should not exceed 5V.}
-\end{tabularx}
-\end{threeparttable}
-\end{table}
+    \begin{table}[h]
+    \begin{threeparttable}
+    \caption{Recommended Operating Conditions}
+    \begin{tabularx}{\textwidth}{l | c c c | c | X}
+        \thickhline
+        \textbf{Parameter} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
+        \textbf{Unit} & \textbf{Conditions} \\
+        \hline
+        Input voltage & 0 & & 5.5* & V \\
+        \hline
+        High-level output current & & & -24 & mA \\
+        \hline
+        Low-level output current & & & 24 & mA \\
+        \hline
+        Input edge rate & & & 10 & ns/V & $0.8V \leq V_I \leq 2.0V$ \\
+        \thickhline
+        \multicolumn{6}{l}{*With the 50\textOmega~termination enabled, the input voltage should not exceed 5V.}
+    \end{tabularx}
+    \end{threeparttable}
+    \end{table}
 
-\begin{table}[h]
-\begin{threeparttable}
-\caption{Electrical Characteristics}
-\begin{tabularx}{\textwidth}{l | c c c | c | X}
-    \thickhline
-    \textbf{Parameter} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
-    \textbf{Unit} & \textbf{Conditions} \\
-    \hline
-    Input clamp diode voltage & & & -1.2 & V & $I_I =-36 mA$ \\
-    \hline
-    Input high voltage & 2.0 & & & V & \\
-    \hline
-    Input low voltage & & & 0.8 & V & \\
-    \hline
-    Output high voltage & 2.0 & & & V & $I_{OH}=-24mA$ \\
-    & 3.1 & & & V & $I_{OH}=-200\mu A$ \\
-    \hline
-    Output low voltage & & & 0.8 & V & $I_{OL}=-24mA$ \\
-    & & & 0.2 & V & $I_{OL}=-200\mu A$ \\
-    \hline
-    Input current & & & 20 & \textmu A & $V_I=5.5V$ \\
-    & & & 2 & \textmu A & $V_I=3.3V$ \\
-    & & & -10 & \textmu A & $V_I=0V$ \\
-    \thickhline
-\end{tabularx}
-\end{threeparttable}
-\end{table}
+    \begin{table}[h]
+    \begin{threeparttable}
+    \caption{Electrical Characteristics}
+    \begin{tabularx}{\textwidth}{l | c c c | c | X}
+        \thickhline
+        \textbf{Parameter} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
+        \textbf{Unit} & \textbf{Conditions} \\
+        \hline
+        Input clamp diode voltage & & & -1.2 & V & $I_I =-36 mA$ \\
+        \hline
+        Input high voltage & 2.0 & & & V & \\
+        \hline
+        Input low voltage & & & 0.8 & V & \\
+        \hline
+        Output high voltage & 2.0 & & & V & $I_{OH}=-24mA$ \\
+        & 3.1 & & & V & $I_{OH}=-200\mu A$ \\
+        \hline
+        Output low voltage & & & 0.8 & V & $I_{OL}=-24mA$ \\
+        & & & 0.2 & V & $I_{OL}=-200\mu A$ \\
+        \hline
+        Input current & & & 20 & \textmu A & $V_I=5.5V$ \\
+        & & & 2 & \textmu A & $V_I=3.3V$ \\
+        & & & -10 & \textmu A & $V_I=0V$ \\
+        \thickhline
+    \end{tabularx}
+    \end{threeparttable}
+    \end{table}
 
 \newpage
 
 \section{Configuring IO Direction \& Termination}
-IO direction and termination must be configured by switches. The termination switches are found at the top and the IO direction switches at the middle of the card respectively.
-\begin{multicols}{2}
-Termination switches between high impedence (OFF) and 50\textOmega~(ON). Note that termination switches are by-channel but IO direction switches are by-bank.
 
-\begin{itemize}
-    \itemsep0em
-    \item IO direction switch closed (\texttt{ON}) \\
-          Fixes the corresponding bank to output. The IO direction cannot be changed by I\textsuperscript{2}C.
-    \item IO direction switch open (OFF) \\
-          The corresponding bank is set to input by default. IO direction \textit{can} be changed by I\textsuperscript{2}C.
-\end{itemize}
-\columnbreak
-\begin{center}
-    \centering
-    \includegraphics[height=1.7in]{mcx_ttl_switches.jpg}
-    \captionof{figure}{Position of switches}
-\end{center}
-\end{multicols}
+    IO direction and termination must be configured by switches. The termination switches are found at the top and the IO direction switches at the middle of the card respectively.
+
+    \begin{multicols}{2}
+
+    Termination switches between high impedence (OFF) and 50\textOmega~(ON). Note that termination switches are by-channel but IO direction switches are by-bank.
+
+    \begin{itemize}
+        \itemsep0em
+        \item IO direction switch closed (\texttt{ON}) \\
+            Fixes the corresponding bank to output. The IO direction cannot be changed by I\textsuperscript{2}C.
+        \item IO direction switch open (OFF) \\
+            The corresponding bank is set to input by default. IO direction \textit{can} be changed by I\textsuperscript{2}C.
+    \end{itemize}
+
+    \columnbreak
+
+    \begin{center}
+        \centering
+        \includegraphics[height=1.7in]{mcx_ttl_switches.jpg}
+        \captionof{figure}{Position of switches}
+    \end{center}
+
+    \end{multicols}
+
+\sysdescsection
+
+    2238 MCX-TTL should be entered in the \texttt{peripherals} list of the corresponding core device in the following format:
+
+    \begin{tcolorbox}[colback=white]
+        \begin{minted}{json}
+            {
+                "type": "dio",
+                "board": "DIO_MCX", // optional
+                "ports": [0],
+                "edge_counter": true, // optional
+                "bank_direction_low": "input", // or "output"
+                "bank_direction_high": "output" // or "input"
+            },
+            {
+                "type": "dio",
+                "board": "DIO_MCX",
+                "ports": [1],
+                "bank_direction_low": "output",
+                "bank_direction_high": "output"
+            }
+        \end{minted}
+    \end{tcolorbox}
+
+    Note that due to its high channel account and double EEM connections 2238 MCX-TTL is entered into a system description as two peripheral entries, each representing two banks.
+
+    The \texttt{edge\_counter} field is boolean and may be specified true or false; a setting \texttt{true} will make a corresponding ARTIQ \texttt{edge\_counter} module available and consume a corresponding amount of additonal gateware resources. If not included, its default value is false. Both \texttt{edge\_counter} and IO direction can be specified separately for each entry.
+
+    For single-EEM operation, use only one of two peripheral entries.
 
 \newpage
+
 \codesection{2238 MCX-TTL card}
 
-Timing accuracy in these examples is well under 1 nanosecond thanks to ARTIQ RTIO infrastructure.
+    Timing accuracy in these examples is well under 1 nanosecond thanks to ARTIQ RTIO infrastructure.
 
-\subsection{One pulse per second}
-The channel should be configured as output in both the gateware and hardware.
-\inputcolorboxminted{firstline=9,lastline=14}{examples/ttl.py}
+    \subsection{One pulse per second}
+    The channel should be configured as output in both the gateware and hardware.
+    \inputcolorboxminted{firstline=9,lastline=14}{examples/ttl.py}
 
-\subsection{Morse code}
-This example demonstrates some basic algorithmic features of the ARTIQ-Python language.
-\inputcolorboxminted{firstline=22,lastline=39}{examples/ttl.py}
+    \subsection{Morse code}
+    This example demonstrates some basic algorithmic features of the ARTIQ-Python language.
+    \inputcolorboxminted{firstline=22,lastline=39}{examples/ttl.py}
 
 \newpage
-\subsection{Edge counting in an 1ms window}
-The channel should be configured as input in both gateware and hardware.
-\inputcolorboxminted{firstline=47,lastline=52}{examples/ttl.py}
 
-This example code uses the software counter, which has a maximum count rate of approximately 1 million events per second.
-If the gateware counter is enabled on the TTL channel, it can typically count up to 125 million events per second:
-\inputcolorboxminted{firstline=60,lastline=65}{examples/ttl.py}
+    \subsection{Edge counting in an 1ms window}
+    The channel should be configured as input in both gateware and hardware.
+    \inputcolorboxminted{firstline=47,lastline=52}{examples/ttl.py}
 
-\subsection{Responding to an external trigger}
-One channel needs to be configured as input, and the other as output.
-\inputcolorboxminted{firstline=74,lastline=80}{examples/ttl.py}
+    This example code uses the software counter, which has a maximum count rate of approximately 1 million events per second.
+    If the gateware counter is enabled on the TTL channel, it can typically count up to 125 million events per second:
+    \inputcolorboxminted{firstline=60,lastline=65}{examples/ttl.py}
+
+    \subsection{Responding to an external trigger}
+    One channel needs to be configured as input, and the other as output.
+    \inputcolorboxminted{firstline=74,lastline=80}{examples/ttl.py}
 
 \ordersection{2238 MCX-TTL}
 

2245.tex

@@ -7,7 +7,7 @@
 \title{2245 LVDS-TTL}
 \author{M-Labs Limited}
 \date{January 2022}
-\revision{Revision 2}
+\revision{Revision 3}
 \companylogo{\includegraphics[height=0.73in]{artiq_sinara.pdf}}
 
 \begin{document}
@@ -16,28 +16,28 @@
 \section{Features}
 
 \begin{itemize}
-\item{16 LVDS-TTL channels.}
-\item{Input- and output-capable}
-\item{No galvanic isolation}
-\item{High speed and low jitter}
-\item{RJ45 connectors}
+    \item{16 LVDS-TTL channels.}
+    \item{Input- and output-capable}
+    \item{No galvanic isolation}
+    \item{High speed and low jitter}
+    \item{RJ45 connectors}
 \end{itemize}
 
 \section{Applications}
 
 \begin{itemize}
-\item{Photon counting}
-\item{External equipment trigger}
-\item{Optical shutter control}
-\item{Serial communication with remote devices}
+    \item{Photon counting}
+    \item{External equipment trigger}
+    \item{Optical shutter control}
+    \item{Serial communication with remote devices}
 \end{itemize}
 
 \section{General Description}
-The 2245 LVDS-TTL card is a 4hp EEM module. It adds general-purpose digital I/O capabilities to carrier cards such as 1124 Kasli and 1125 Kasli-SoC.
+    The 2245 LVDS-TTL card is a 4hp EEM module. It adds general-purpose digital I/O capabilities to carrier cards such as 1124 Kasli and 1125 Kasli-SoC.
 
-Each card provides sixteen total digital channels, with four RJ45 connectors in the front panel, controlled through 2 EEM connectors. Each RJ45 connector exposes four LVDS digital channels. Each individual EEM connector controls eight channels independently. Single EEM operation is possible. The direction (input or output) of each channel can be selected individually using DIP switches.
+    Each card provides sixteen total digital channels, with four RJ45 connectors in the front panel, controlled through 2 EEM connectors. Each RJ45 connector exposes four LVDS digital channels. Each individual EEM connector controls eight channels independently. Single EEM operation is possible. The direction (input or output) of each channel can be selected individually using DIP switches.
 
-Outputs are intended to drive 100\textOmega~loads and inputs are 100\textOmega~terminated. This card can achieve higher speed and lower jitter than the isolated 2118/2128 BNC/SMA-TTL cards. Only shielded Ethernet Cat-6 cables should be connected.
+    Outputs are intended to drive 100\textOmega~loads and inputs are 100\textOmega~terminated. This card can achieve higher speed and lower jitter than the isolated 2118/2128 BNC/SMA-TTL cards. Only shielded Ethernet Cat-6 cables should be connected.
 
 % Switch to next column
 \vfill\break
@@ -297,7 +297,7 @@ Outputs are intended to drive 100\textOmega~loads and inputs are 100\textOmega~t
 \begin{figure}[hbt!]
     \centering
     \includegraphics[angle=90, height=1.7in]{photo2245.jpg}
-    \includegraphics[angle=90, height=0.4in]{DIO_RJ45_FP.pdf}
+    \includegraphics[angle=90, height=0.4in]{fp2245.pdf}
     \caption{LVDS-TTL card and front panel}
 \end{figure}
 
@@ -310,316 +310,366 @@ Outputs are intended to drive 100\textOmega~loads and inputs are 100\textOmega~t
 
 \section{Electrical Specifications}
 
-All specifications are in $-40\degree C \leq T_A \leq 85\degree C$ unless otherwise noted. Information in this section is based on the datasheet of the repeater IC (FIN1101K8X\footnote{\label{repeaters}\url{https://www.onsemi.com/pdf/datasheet/fin1101-d.pdf}}).
+    All specifications are in $-40\degree C \leq T_A \leq 85\degree C$ unless otherwise noted. Information in this section is based on the datasheet of the repeater IC (FIN1101K8X\footnote{\label{repeaters}\url{https://www.onsemi.com/pdf/datasheet/fin1101-d.pdf}}).
 
-\begin{table}[h]
-\begin{threeparttable}
-\caption{Recommended Input Voltage}
-\begin{tabularx}{\textwidth}{l | c | c c c | c | X}
-    \thickhline
-    \textbf{Parameter} & \textbf{Symbol} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
-    \textbf{Unit} & \textbf{Conditions} \\
-    \hline
-    Magnitude of differential input & $|V_{ID}|$ & 0.1 & & 3.3 & V \\
-    \hline
-    Common mode input & $V_{IC}$ & $|V_{ID}|/2$ & & $3.3-|V_{ID}|/2$ & V \\
-    \hline
-    Differential input threshold HIGH & $V_{TH}$ & & & 100 & mV & \\
-    \hline
-    Differential input threshold LOW & $V_{TL}$ & -100 & & & mV & \\
-    \thickhline
-\end{tabularx}
-\end{threeparttable}
-\end{table}
+    \begin{table}[h!]
+    \begin{threeparttable}
+    \caption{Recommended Input Voltage}
+    \begin{tabularx}{\textwidth}{l | c | c c c | c | X}
+        \thickhline
+        \textbf{Parameter} & \textbf{Symbol} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
+        \textbf{Unit} & \textbf{Conditions} \\
+        \hline
+        Magnitude of differential input & $|V_{ID}|$ & 0.1 & & 3.3 & V \\
+        \hline
+        Common mode input & $V_{IC}$ & $|V_{ID}|/2$ & & $3.3-|V_{ID}|/2$ & V \\
+        \hline
+        Differential input threshold HIGH & $V_{TH}$ & & & 100 & mV & \\
+        \hline
+        Differential input threshold LOW & $V_{TL}$ & -100 & & & mV & \\
+        \thickhline
+    \end{tabularx}
+    \end{threeparttable}
+    \end{table}
 
-All typical values of DC specifications are at $T_A = 25\degree C$.
+    All typical values of DC specifications are at $T_A = 25\degree C$.
 
-\begin{table}[h]
-\begin{threeparttable}
-\caption{DC Specifications}
-\begin{tabularx}{\textwidth}{l | c | c c c | c | X}
-    \thickhline
-    \textbf{Parameter} & \textbf{Symbol} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
-    \textbf{Unit} & \textbf{Conditions} \\
-    \hline
-    Output differential voltage & $V_{OD}$ & 250 & 330 & 450 & mV & \multirow{4}{*}{With 100$\Omega$ load.} \\
-    \cline{0-5}
-    $|V_{OD}|$ change (LOW-to-HIGH) & $\Delta V_{OD}$ & & & 25 & mV & \\
-    \cline{0-5}
-    Offset voltage & $V_{OS}$ & 1.125 & 1.23 & 1.375 & V & \\
-    \cline{0-5}
-    $|V_{OS}|$ change (LOW-to-HIGH) & $\Delta V_{OS}$ & & & 25 & mV & \\
-    \hline
-    Short circuit output current & $I_{OS}$ & & $\pm3.4$ & $\pm6$ & mA & \\
-    \hline
-    Input current & $I_{IN}$ & & & $\pm20$ & \textmu A & Recommended input voltage \\
-    \thickhline
-\end{tabularx}
-\end{threeparttable}
-\end{table}
+    \begin{table}[h!]
+    \begin{threeparttable}
+    \caption{DC Specifications}
+    \begin{tabularx}{\textwidth}{l | c | c c c | c | X}
+        \thickhline
+        \textbf{Parameter} & \textbf{Symbol} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
+        \textbf{Unit} & \textbf{Conditions} \\
+        \hline
+        Output differential voltage & $V_{OD}$ & 250 & 330 & 450 & mV & \multirow{4}{*}{With 100$\Omega$ load.} \\
+        \cline{0-5}
+        $|V_{OD}|$ change (LOW-to-HIGH) & $\Delta V_{OD}$ & & & 25 & mV & \\
+        \cline{0-5}
+        Offset voltage & $V_{OS}$ & 1.125 & 1.23 & 1.375 & V & \\
+        \cline{0-5}
+        $|V_{OS}|$ change (LOW-to-HIGH) & $\Delta V_{OS}$ & & & 25 & mV & \\
+        \hline
+        Short circuit output current & $I_{OS}$ & & $\pm3.4$ & $\pm6$ & mA & \\
+        \hline
+        Input current & $I_{IN}$ & & & $\pm20$ & \textmu A & Recommended input voltage \\
+        \thickhline
+    \end{tabularx}
+    \end{threeparttable}
+    \end{table}
 
-All typical values of AC specifications are at $T_A = 25\degree C$, $V_{ID} = 300mV$, $V_{IC} = 1.3V$ unless otherwise given.
+    All typical values of AC specifications are at $T_A = 25\degree C$, $V_{ID} = 300mV$, $V_{IC} = 1.3V$ unless otherwise given.
 
-\begin{table}[h]
-\begin{threeparttable}
-\caption{AC Specifications}
-\begin{tabularx}{\textwidth}{l | c c c | c | X}
-    \thickhline
-    \textbf{Parameter} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
-    \textbf{Unit} & \textbf{Conditions} \\
-    \hline
-    Differential output rise time & \multirow{2}{*}{0.29} & \multirow{2}{*}{0.40} & \multirow{2}{*}{0.58} & \multirow{2}{*}{ns} & Duty cycle = 50\%.\\
-    (20\% to 80\%) & & & & &    \\
-    \cline{0-5}
-    Differential output fall time & \multirow{2}{*}{0.29} & \multirow{2}{*}{0.40} & \multirow{2}{*}{0.58} & \multirow{2}{*}{ns} & \\
-    (80\% to 20\%) & & & & & \\
-    \cline{0-5}
-    Pulse width distortion & & 0.01 & 0.2 & ns & \\
-    \hline
-    LVDS data jitter, & & \multirow{2}{*}{85} & \multirow{2}{*}{125} & \multirow{2}{*}{ps} & $PRBS=2^{23}-1$\\
-    deterministic & & & & & 800 Mbps\\
-    \hline
-    LVDS clock jitter, & & \multirow{2}{*}{2.1} & \multirow{2}{*}{3.5} & \multirow{2}{*}{ps} & \multirow{2}{*}{400 MHz clock}\\
-    random (RMS) & & & & & \\
-    \thickhline
-\end{tabularx}
-\end{threeparttable}
-\end{table}
+    \begin{table}[h!]
+    \begin{threeparttable}
+    \caption{AC Specifications}
+    \begin{tabularx}{\textwidth}{l | c c c | c | X}
+        \thickhline
+        \textbf{Parameter} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
+        \textbf{Unit} & \textbf{Conditions} \\
+        \hline
+        Differential output rise time & \multirow{2}{*}{0.29} & \multirow{2}{*}{0.40} & \multirow{2}{*}{0.58} & \multirow{2}{*}{ns} & Duty cycle = 50\%.\\
+        (20\% to 80\%) & & & & &    \\
+        \cline{0-5}
+        Differential output fall time & \multirow{2}{*}{0.29} & \multirow{2}{*}{0.40} & \multirow{2}{*}{0.58} & \multirow{2}{*}{ns} & \\
+        (80\% to 20\%) & & & & & \\
+        \cline{0-5}
+        Pulse width distortion & & 0.01 & 0.2 & ns & \\
+        \hline
+        LVDS data jitter, & & \multirow{2}{*}{85} & \multirow{2}{*}{125} & \multirow{2}{*}{ps} & $PRBS=2^{23}-1$\\
+        deterministic & & & & & 800 Mbps\\
+        \hline
+    \end{tabularx}
+    \end{threeparttable}
+    \end{table}
 
 \newpage
 
-\section{Configuring IO Direction \& Termination}
-\begin{multicols}{2}
-The IO direction of each channel can be configured by DIP switches, which are found at the top of the card.
-\begin{itemize}
-    \itemsep0em
-    \item IO direction switch closed (\texttt{ON}) \\
-          Fixes the corresponding bank to output. The IO direction cannot be changed by I\textsuperscript{2}C.
-    \item IO direction switch open (OFF) \\
-          The corresponding bank is set to input by default. IO direction \textit{can} be changed by I\textsuperscript{2}C.
-\end{itemize}
+    \begin{table}[h!]
+        \begin{threeparttable}
+        \caption{AC Specifications, cont.}
+        \begin{tabularx}{\textwidth}{l | c c c | c | X}
+            \thickhline
+            \textbf{Parameter} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
+            \textbf{Unit} & \textbf{Conditions} \\
+            \hline
+            LVDS clock jitter, & & \multirow{2}{*}{2.1} & \multirow{2}{*}{3.5} & \multirow{2}{*}{ps} & \multirow{2}{*}{400 MHz clock}\\
+            random (RMS) & & & & & \\
+            \thickhline
+        \end{tabularx}
+        \end{threeparttable}
+        \end{table}
 
-\vspace*{\fill}\columnbreak
-\begin{center}
-    \centering
-    \includegraphics[height=1.5in]{lvds_ttl_switches.jpg}
-    \captionof{figure}{Position of switches}
-\end{center}
-\end{multicols}
+\section{Configuring IO Direction \& Termination}
+
+    \begin{multicols}{2}
+
+    The IO direction of each channel can be configured by DIP switches, which are found at the top of the card.
+    \begin{itemize}
+        \itemsep0em
+        \item IO direction switch closed (\texttt{ON}) \\
+            Fixes the corresponding bank to output. The IO direction cannot be changed by I\textsuperscript{2}C.
+        \item IO direction switch open (OFF) \\
+            The corresponding bank is set to input by default. IO direction \textit{can} be changed by I\textsuperscript{2}C.
+    \end{itemize}
+
+    \vspace*{\fill}\columnbreak
+
+    \begin{center}
+        \centering
+        \includegraphics[height=1.5in]{lvds_ttl_switches.jpg}
+        \captionof{figure}{Position of switches}
+    \end{center}
+
+    \end{multicols}
+
+\sysdescsection
+
+    2245 LVDS-TTL should be entered in the \texttt{peripherals} list of the corresponding core device in the following format:
+
+    \begin{tcolorbox}[colback=white]
+        \begin{minted}{json}
+            {
+                "type": "dio",
+                "board": "DIO_LVDS", // optional
+                "ports": [0],
+                "edge_counter": true, // optional
+                "bank_direction_low": "input", // or "output"
+                "bank_direction_high": "output" // or "input"
+            },
+            {
+                "type": "dio",
+                "board": "DIO_LVDS",
+                "ports": [1],
+                "bank_direction_low": "output",
+                "bank_direction_high": "output"
+            }
+        \end{minted}
+    \end{tcolorbox}
+
+    Note that due to its high channel account and double EEM connections 2245 LVDS-TTL is entered into a system description as two peripheral entries, each representing two banks.
+
+    The \texttt{edge\_counter} field is boolean and may be specified true or false; a setting \texttt{true} will make a corresponding ARTIQ \texttt{edge\_counter} module available and consume a corresponding amount of additonal gateware resources. If not included, its default value is false. Both \texttt{edge\_counter} and IO direction can be specified separately for each entry.
+
+    For single-EEM operation, use only one of two peripheral entries.
 
 \newpage
 
 \codesection{2245 LVDS-TTL card}
 
-Timing accuracy in these examples is well under 1 nanosecond thanks to ARTIQ RTIO infrastructure.
+    Timing accuracy in these examples is well under 1 nanosecond thanks to ARTIQ RTIO infrastructure.
 
-\subsection{One pulse per second}
-The channel should be configured as output in both gateware and hardware.
-\inputcolorboxminted{firstline=9,lastline=14}{examples/ttl.py}
+    \subsection{One pulse per second}
+    The channel should be configured as output in both gateware and hardware.
+    \inputcolorboxminted{firstline=9,lastline=14}{examples/ttl.py}
 
-\subsection{Morse code}
-This example demonstrates some basic algorithmic features of the ARTIQ-Python language.
-\inputcolorboxminted{firstline=22,lastline=39}{examples/ttl.py}
+    \subsection{Morse code}
+    This example demonstrates some basic algorithmic features of the ARTIQ-Python language.
+    \inputcolorboxminted{firstline=22,lastline=39}{examples/ttl.py}
 
 \newpage
-\subsection{Counting rising edges in a 1ms window}
-The channel should be configured as input in both gateware and hardware.
-\inputcolorboxminted{firstline=47,lastline=52}{examples/ttl.py}
 
-This example code uses the software counter, which has a maximum count rate of approximately 1 million events per second.
-If the gateware counter is enabled on the TTL channel, it can typically count up to 125 million events per second:
-\inputcolorboxminted{firstline=60,lastline=65}{examples/ttl.py}
+    \subsection{Counting rising edges in a 1ms window}
+    The channel should be configured as input in both gateware and hardware.
+    \inputcolorboxminted{firstline=47,lastline=52}{examples/ttl.py}
 
-\subsection{Responding to an external trigger}
-One channel needs to be configured as input, and the other as output.
-\inputcolorboxminted{firstline=74,lastline=80}{examples/ttl.py}
+    This example code uses the software counter, which has a maximum count rate of approximately 1 million events per second.
+    If the gateware counter is enabled on the TTL channel, it can typically count up to 125 million events per second:
+    \inputcolorboxminted{firstline=60,lastline=65}{examples/ttl.py}
 
-\newcommand{\wrapspacer}[1]% #1 = special text
-{\bgroup
-  \sbox0{\begin{minipage}{\linewidth}\hrule height0pt
-    #1\hrule height0pt
-    \end{minipage}}%
-  \dimen0=\dimexpr \ht0+\dp0\relax
-  \loop\ifdim\dimen0>\baselineskip
-    \strut\vspace{-\baselineskip}\newline
-    \advance\dimen0 by -\baselineskip
-  \repeat
-  \noindent\strut\usebox0\par
-\egroup}
+    \subsection{Responding to an external trigger}
+    One channel needs to be configured as input, and the other as output.
+    \inputcolorboxminted{firstline=74,lastline=80}{examples/ttl.py}
+
+    \newcommand{\wrapspacer}[1]% #1 = special text
+    {\bgroup
+    \sbox0{\begin{minipage}{\linewidth}\hrule height0pt
+        #1\hrule height0pt
+        \end{minipage}}%
+    \dimen0=\dimexpr \ht0+\dp0\relax
+    \loop\ifdim\dimen0>\baselineskip
+        \strut\vspace{-\baselineskip}\newline
+        \advance\dimen0 by -\baselineskip
+    \repeat
+    \noindent\strut\usebox0\par
+    \egroup}
+
+    \subsection{SPI Master Device}
+    If one of the two card EEM ports is configured as \texttt{dio\char`_spi} instead of \texttt{dio}, its associated TTL channels can be configured as SPI master devices. Invocation of an SPI transfer follows this pattern:
+    \begin{enumerate}
+        % The config register can be set using set_config.
+        % However, the only difference between these 2 methods is that set_config accepts an arbitrary
+        % frequency, then translate into the rough frequency divisor for set_config_mu.
+        % It doesn't guarantee such frequency would be set as the SPI frequency
+
+        % In addition, finding clock division is quite easy. set_config_mu seems to be a more
+        % straight-forward & representative of the actual implementation.
+        \item Set the \texttt{config} register (e.g. using \texttt{set\char`_config\char`_mu()}).
+        \item Start the SPI transfer by writing the \texttt{data} register using \texttt{write()}.
+        \item If the data from the SPI slave is to be read (i.e. \texttt{SPI\char`_INPUT} was set in \texttt{config}), invoke \texttt{read()} to read.
+
+    \end{enumerate}
+
+    The list of configurations supported in the gateware are listed as below:
+
+    \begin{table}[h]
+        \centering
+        \begin{tabular}{|c|l|}
+        \hline
+        Flag                                    & Description                                                             \\ \hline
+        \texttt{SPI\char`_OFFLINE}              & Switch all pins to high impedance mode.                                 \\ \hline
+        \texttt{SPI\char`_END}                  & Next SPI transfer is the last of the transcation.                       \\ \hline
+        \texttt{SPI\char`_INPUT}                & Submit SPI read data as RTIO input event when the transfer is complete. \\ \hline
+        \texttt{SPI\char`_CS\char`_POLARITY}    & Active level of chip select (CS)                                        \\ \hline
+        \texttt{SPI\char`_CLK\char`_POLARITY}   & Idle level of serial clock (SCK)                                        \\ \hline
+        \texttt{SPI\char`_CLK\char`_PHASE}      & Data is sampled on falling edge \& shifted out on rising edge.          \\ \hline
+        \texttt{SPI\char`_LSB\char`_FIRST}      & LSB is the first on bit on the wire.                                    \\ \hline
+        \texttt{SPI\char`_HALF\char`_DUPLEX}    & Use 3-wire SPI, where MOSI is both input \& output capable.             \\ \hline
+        \end{tabular}
+    \end{table}
+
+    The following ARTIQ example demonstrates the flow of an SPI transaction on a typical SPI setup with 3 homogeneous slaves. The direction switches on the LVDS-TTL card should be set to the correct IO direction for all relevant channels before powering on.
 
 \newpage
-\subsection{SPI Master Device}
-If one of the two card EEM ports is configured as \texttt{dio\char`_spi} instead of \texttt{dio}, its associated TTL channels can be configured as SPI master devices. Invocation of an SPI transfer follows this pattern:
-\begin{enumerate}
-    % The config register can be set using set_config.
-    % However, the only difference between these 2 methods is that set_config accepts an arbitrary
-    % frequency, then translate into the rough frequency divisor for set_config_mu.
-    % It doesn't guarantee such frequency would be set as the SPI frequency
 
-    % In addition, finding clock division is quite easy. set_config_mu seems to be a more
-    % straight-forward & representative of the actual implementation.
-    \item Set the \texttt{config} register (e.g. using \texttt{set\char`_config\char`_mu()}).
-    \item Start the SPI transfer by writing the \texttt{data} register using \texttt{write()}.
-    \item If the data from the SPI slave is to be read (i.e. \texttt{SPI\char`_INPUT} was set in \texttt{config}), invoke \texttt{read()} to read.
+    \begin{center}
+        \begin{circuitikz}[european, scale=1, every label/.append style={align=center}]
+            % SPI master
+            \draw (0, 1.8) node[twoportshape, t={}, circuitikz/bipoles/twoport/width=2.8, circuitikz/bipoles/twoport/height=2, scale=1] (master) {};
+            \node [label={center:\large{SPI Master}}] at (-0.6, 2.05) {};
+            \node [label={center:\large{(LVDS-TTL)}}] at (-0.6, 1.55) {};
+            \node [label=left:{SCK}] at (2, 2.8) {};
+            \node [label=left:{MOSI}] at (2, 2.4) {};
+            \node [label=left:{MISO}] at (2, 2.0) {};
+            \node [label=left:{CS0}] at (2, 1.6) {};
+            \node [label=left:{CS1}] at (2, 1.2) {};
+            \node [label=left:{CS2}] at (2, 0.8) {};
 
-\end{enumerate}
+            % SPI slaves
+            % The top one will have its SCK, MOSI, MISO aligned with the master, for wiring simplicity
+            \draw (7, 2.2) node[twoportshape, t={}, circuitikz/bipoles/twoport/width=2.8, circuitikz/bipoles/twoport/height=1.4, scale=1] (slave0) {};
+            \node [label={center:\large{SPI Slave 0}}] at (7.6, 2.2) {};
+            \node [label=right:{SCK}] at (5, 2.8) {};
+            \node [label=right:{MOSI}] at (5, 2.4) {};
+            \node [label=right:{MISO}] at (5, 2.0) {};
+            \node [label=right:{$\mathrm{\overline{CS}}$}] at (5, 1.6) {};
 
-The list of configurations supported in the gateware are listed as below:
+            % The top one will have its SCK, MOSI, MISO aligned with the master, for wiring simplicity
+            \draw (7, 0) node[twoportshape, t={}, circuitikz/bipoles/twoport/width=2.8, circuitikz/bipoles/twoport/height=1.4, scale=1] (slave1) {};
+            \node [label={center:\large{SPI Slave 1}}] at (7.6, 0) {};
+            \node [label=right:{SCK}] at (5, 0.6) {};
+            \node [label=right:{MOSI}] at (5, 0.2) {};
+            \node [label=right:{MISO}] at (5, -0.2) {};
+            \node [label=right:{$\mathrm{\overline{CS}}$}] at (5, -0.6) {};
 
-\begin{table}[h]
-    \centering
-    \begin{tabular}{|c|l|}
-    \hline
-    Flag                                    & Description                                                             \\ \hline
-    \texttt{SPI\char`_OFFLINE}              & Switch all pins to high impedance mode.                                 \\ \hline
-    \texttt{SPI\char`_END}                  & Next SPI transfer is the last of the transcation.                       \\ \hline
-    \texttt{SPI\char`_INPUT}                & Submit SPI read data as RTIO input event when the transfer is complete. \\ \hline
-    \texttt{SPI\char`_CS\char`_POLARITY}    & Active level of chip select (CS)                                        \\ \hline
-    \texttt{SPI\char`_CLK\char`_POLARITY}   & Idle level of serial clock (SCK)                                        \\ \hline
-    \texttt{SPI\char`_CLK\char`_PHASE}      & Data is sampled on falling edge \& shifted out on rising edge.          \\ \hline
-    \texttt{SPI\char`_LSB\char`_FIRST}      & LSB is the first on bit on the wire.                                    \\ \hline
-    \texttt{SPI\char`_HALF\char`_DUPLEX}    & Use 3-wire SPI, where MOSI is both input \& output capable.             \\ \hline
-    \end{tabular}
-\end{table}
+            % The top one will have its SCK, MOSI, MISO aligned with the master, for wiring simplicity
+            \draw (7, -2.2) node[twoportshape, t={}, circuitikz/bipoles/twoport/width=2.8, circuitikz/bipoles/twoport/height=1.4, scale=1] (slave2) {};
+            \node [label={center:\large{SPI Slave 2}}] at (7.6, -2.2) {};
+            \node [label=right:{SCK}] at (5, -1.6) {};
+            \node [label=right:{MOSI}] at (5, -2.0) {};
+            \node [label=right:{MISO}] at (5, -2.4) {};
+            \node [label=right:{$\mathrm{\overline{CS}}$}] at (5, -2.8) {};
 
-The following ARTIQ example demonstrates the flow of an SPI transaction on a typical SPI setup with 3 homogeneous slaves.
-The direction switches on the LVDS-TTL card should be set to the correct IO direction for all relevant channels before powering on.
-\begin{center}
-    \begin{circuitikz}[european, scale=1, every label/.append style={align=center}]
-        % SPI master
-        \draw (0, 1.8) node[twoportshape, t={}, circuitikz/bipoles/twoport/width=2.8, circuitikz/bipoles/twoport/height=2, scale=1] (master) {};
-        \node [label={center:\large{SPI Master}}] at (-0.6, 2.05) {};
-        \node [label={center:\large{(LVDS-TTL)}}] at (-0.6, 1.55) {};
-        \node [label=left:{SCK}] at (2, 2.8) {};
-        \node [label=left:{MOSI}] at (2, 2.4) {};
-        \node [label=left:{MISO}] at (2, 2.0) {};
-        \node [label=left:{CS0}] at (2, 1.6) {};
-        \node [label=left:{CS1}] at (2, 1.2) {};
-        \node [label=left:{CS2}] at (2, 0.8) {};
+            % Connect the master to slave 0
+            \draw [-latexslim] (1.95, 2.8) -- (5.05, 2.8);
+            \draw [-latexslim] (1.95, 2.4) -- (5.05, 2.4);
+            \draw [latexslim-] (1.95, 2.0) -- (5.05, 2.0);
+            \draw [-latexslim] (1.95, 1.6) -- (5.05, 1.6);
 
-        % SPI slaves
-        % The top one will have its SCK, MOSI, MISO aligned with the master, for wiring simplicity
-        \draw (7, 2.2) node[twoportshape, t={}, circuitikz/bipoles/twoport/width=2.8, circuitikz/bipoles/twoport/height=1.4, scale=1] (slave0) {};
-        \node [label={center:\large{SPI Slave 0}}] at (7.6, 2.2) {};
-        \node [label=right:{SCK}] at (5, 2.8) {};
-        \node [label=right:{MOSI}] at (5, 2.4) {};
-        \node [label=right:{MISO}] at (5, 2.0) {};
-        \node [label=right:{$\mathrm{\overline{CS}}$}] at (5, 1.6) {};
+            % Connect slave 1
+            \draw [-latexslim] (4.2, 2.8) -- (4.2, 0.6) -- (5.05, 0.6);
+            \draw [-latexslim] (3.8, 2.4) -- (3.8, 0.2) -- (5.05, 0.2);
+            \draw [-] (3.4, 2.0) -- (3.4, -0.2) -- (5.05, -0.2);
+            \draw [-latexslim] (1.95, 1.2) -- (3.0, 1.2) -- (3.0, -0.6) -- (5.05, -0.6);
 
-        % The top one will have its SCK, MOSI, MISO aligned with the master, for wiring simplicity
-        \draw (7, 0) node[twoportshape, t={}, circuitikz/bipoles/twoport/width=2.8, circuitikz/bipoles/twoport/height=1.4, scale=1] (slave1) {};
-        \node [label={center:\large{SPI Slave 1}}] at (7.6, 0) {};
-        \node [label=right:{SCK}] at (5, 0.6) {};
-        \node [label=right:{MOSI}] at (5, 0.2) {};
-        \node [label=right:{MISO}] at (5, -0.2) {};
-        \node [label=right:{$\mathrm{\overline{CS}}$}] at (5, -0.6) {};
+            % Connect slave 2
+            \draw [-latexslim] (4.2, 0.6) -- (4.2, -1.6) -- (5.05, -1.6);
+            \draw [-latexslim] (3.8, 0.2) -- (3.8, -2.0) -- (5.05, -2.0);
+            \draw [-] (3.4, -0.2) -- (3.4, -2.4) -- (5.05, -2.4);
+            \draw [-latexslim] (1.95, 0.8) -- (2.6, 0.8) -- (2.6, -2.8) -- (5.05, -2.8);
 
-        % The top one will have its SCK, MOSI, MISO aligned with the master, for wiring simplicity
-        \draw (7, -2.2) node[twoportshape, t={}, circuitikz/bipoles/twoport/width=2.8, circuitikz/bipoles/twoport/height=1.4, scale=1] (slave2) {};
-        \node [label={center:\large{SPI Slave 2}}] at (7.6, -2.2) {};
-        \node [label=right:{SCK}] at (5, -1.6) {};
-        \node [label=right:{MOSI}] at (5, -2.0) {};
-        \node [label=right:{MISO}] at (5, -2.4) {};
-        \node [label=right:{$\mathrm{\overline{CS}}$}] at (5, -2.8) {};
+            % Add dot to intersection to distinguish from overlaps
+            \node at (4.2, 2.8)[circle,fill,inner sep=0.7pt]{};
+            \node at (3.8, 2.4)[circle,fill,inner sep=0.7pt]{};
+            \node at (3.4, 2.0)[circle,fill,inner sep=0.7pt]{};
+            \node at (4.2, 0.6)[circle,fill,inner sep=0.7pt]{};
+            \node at (3.8, 0.2)[circle,fill,inner sep=0.7pt]{};
+            \node at (3.4, -0.2)[circle,fill,inner sep=0.7pt]{};
 
-        % Connect the master to slave 0
-        \draw [-latexslim] (1.95, 2.8) -- (5.05, 2.8);
-        \draw [-latexslim] (1.95, 2.4) -- (5.05, 2.4);
-        \draw [latexslim-] (1.95, 2.0) -- (5.05, 2.0);
-        \draw [-latexslim] (1.95, 1.6) -- (5.05, 1.6);
+        \end{circuitikz}
+    \end{center}
 
-        % Connect slave 1
-        \draw [-latexslim] (4.2, 2.8) -- (4.2, 0.6) -- (5.05, 0.6);
-        \draw [-latexslim] (3.8, 2.4) -- (3.8, 0.2) -- (5.05, 0.2);
-        \draw [-] (3.4, 2.0) -- (3.4, -0.2) -- (5.05, -0.2);
-        \draw [-latexslim] (1.95, 1.2) -- (3.0, 1.2) -- (3.0, -0.6) -- (5.05, -0.6);
-
-        % Connect slave 2
-        \draw [-latexslim] (4.2, 0.6) -- (4.2, -1.6) -- (5.05, -1.6);
-        \draw [-latexslim] (3.8, 0.2) -- (3.8, -2.0) -- (5.05, -2.0);
-        \draw [-] (3.4, -0.2) -- (3.4, -2.4) -- (5.05, -2.4);
-        \draw [-latexslim] (1.95, 0.8) -- (2.6, 0.8) -- (2.6, -2.8) -- (5.05, -2.8);
-
-        % Add dot to intersection to distinguish from overlaps
-        \node at (4.2, 2.8)[circle,fill,inner sep=0.7pt]{};
-        \node at (3.8, 2.4)[circle,fill,inner sep=0.7pt]{};
-        \node at (3.4, 2.0)[circle,fill,inner sep=0.7pt]{};
-        \node at (4.2, 0.6)[circle,fill,inner sep=0.7pt]{};
-        \node at (3.8, 0.2)[circle,fill,inner sep=0.7pt]{};
-        \node at (3.4, -0.2)[circle,fill,inner sep=0.7pt]{};
-
-    \end{circuitikz}
-\end{center}
+    \subsubsection{SPI Configuration}
+    The following examples will assume the SPI communication has the following properties:
+    \begin{itemize}
+        \item Chip select (CS) is active low
+        \item Serial clock (SCK) idle level is low
+        \item Data is sampled on rising edge of SCK \& shifted out on falling edge of SCK
+        \item Most significant bit (MSB) first
+        \item Full duplex
+    \end{itemize}
 
 \newpage
-\subsubsection{SPI Configuration}
-The following examples will assume the SPI communication has the following properties:
-\begin{itemize}
-    \item Chip select (CS) is active low
-    \item Serial clock (SCK) idle level is low
-    \item Data is sampled on rising edge of SCK \& shifted out on falling edge of SCK
-    \item Most significant bit (MSB) first
-    \item Full duplex
-\end{itemize}
-The baseline configuration for an \texttt{SPIMaster} instance can be defined as such:
-\inputcolorboxminted[0]{firstline=2,lastline=8}{examples/spi.py}
-The \texttt{SPI\char`_END} \& \texttt{SPI\char`_INPUT} flags will be modified during runtime in the following example.
 
-\subsubsection{SPI frequency}
-Frequency of the SPI clock must be the result of RTIO clock frequency divided by an integer factor in [2, 257]. In the folowing examples, the SPI frequency will be set to 1 MHz by dividing the RTIO frequency (125 MHz) by 125.
-\inputcolorboxminted[0]{firstline=10,lastline=10}{examples/spi.py}
+    The baseline configuration for an \texttt{SPIMaster} instance can be defined as such:
+    \inputcolorboxminted[0]{firstline=2,lastline=8}{examples/spi.py}
+    The \texttt{SPI\char`_END} \& \texttt{SPI\char`_INPUT} flags will be modified during runtime in the following example.
 
-\subsubsection{SPI write}
-Typically, an SPI write operation involves sending an instruction and data to the SPI slaves. Suppose the instruction and data are 8 bits and 32 bits respectively. The timing diagram of such a write operation is shown in the following:
+    \subsubsection{SPI frequency}
+    Frequency of the SPI clock must be the result of RTIO clock frequency divided by an integer factor in [2, 257]. In the folowing examples, the SPI frequency will be set to 1 MHz by dividing the RTIO frequency (125 MHz) by 125.
+    \inputcolorboxminted[0]{firstline=10,lastline=10}{examples/spi.py}
 
-\begin{center}
-\begin{tikztimingtable}
-    [
-        timing/d/background/.style={fill=white},
-        timing/lslope=0.2
-    ]
-        $\mathrm{\overline{CS}}$ & H51{L}H \\
-        SCK     & LL31{T}; 2{[dotted] T}; 17{T} L \\
-        % The better approach is to use pass the counter (\tikztimingcounter{Q}) to a macro,
-        % then print the label from macro. But it turns out tikz-timing will print
-        % the counter value separately, even with an additional macro.
-        % Therefore, it does not work properly.
-        MOSI & [timing/counter/new={char=I, reset char=J, reset type=arg, increment=-1, text format=I}, timing/counter/new={char=A, reset char=R, reset type=arg, increment=-1, text format=D}]
-        UJ{7}8{2I}R{31}8{2A}; [dotted] D [dotted] D{}; R{7}8{2A}2U \\
-        MOSI & 53U \\
-\end{tikztimingtable}%
-\end{center}
+    \subsubsection{SPI write}
+    Typically, an SPI write operation involves sending an instruction and data to the SPI slaves. Suppose the instruction and data are 8 bits and 32 bits respectively. The timing diagram of such a write operation is shown in the following:
+
+    \begin{center}
+    \begin{tikztimingtable}
+        [
+            timing/d/background/.style={fill=white},
+            timing/lslope=0.2
+        ]
+            $\mathrm{\overline{CS}}$ & H51{L}H \\
+            SCK     & LL31{T}; 2{[dotted] T}; 17{T} L \\
+            % The better approach is to use pass the counter (\tikztimingcounter{Q}) to a macro,
+            % then print the label from macro. But it turns out tikz-timing will print
+            % the counter value separately, even with an additional macro.
+            % Therefore, it does not work properly.
+            MOSI & [timing/counter/new={char=I, reset char=J, reset type=arg, increment=-1, text format=I}, timing/counter/new={char=A, reset char=R, reset type=arg, increment=-1, text format=D}]
+            UJ{7}8{2I}R{31}8{2A}; [dotted] D [dotted] D{}; R{7}8{2A}2U \\
+            MOSI & 53U \\
+    \end{tikztimingtable}%
+    \end{center}
+
+    Suppose the instruction is \texttt{0x13}, while the data is \texttt{0xDEADBEEF}. In addition, both slave 1 \& 2 are selected. This SPI transaction can be performed with the following code:
+    \inputcolorboxminted{firstline=18,lastline=27}{examples/spi.py}
 
 \newpage
-Suppose the instruction is \texttt{0x13}, while the data is \texttt{0xDEADBEEF}. In addition, both slave 1 \& 2 are selected. This SPI transaction can be performed with the following code:
-\inputcolorboxminted{firstline=18,lastline=27}{examples/spi.py}
 
-\subsubsection{SPI read}
-A 32-bit read is represented by the following timing diagram:
+    \subsubsection{SPI read}
+    A 32-bit read is represented by the following timing diagram:
 
-\begin{center}
-\begin{tikztimingtable}
-    [
-        timing/d/background/.style={fill=white},
-        timing/lslope=0.2
-    ]
-        $\mathrm{\overline{CS}}$ & H51{L}H \\
-        SCK     & LL31{T}; 2{[dotted] T}; 17{T} L \\
-        % The better approach is to use pass the counter (\tikztimingcounter{Q}) to a macro,
-        % then print the label from macro. But it turns out tikz-timing will print
-        % the counter value separately, even with an additional macro.
-        % Therefore, it does not work properly.
-        MOSI & [timing/counter/new={char=I, reset char=J, reset type=arg, increment=-1, text format=I}]
-        UJ{7}8{2I}36U \\
-        MOSI & [timing/counter/new={char=A, reset char=R, reset type=arg, increment=-1, text format=D}]
-        17UR{31}8{2A}; [dotted] D [dotted] D{}; R{7}8{2A}2U \\
-\end{tikztimingtable}%
-\end{center}
+    \begin{center}
+    \begin{tikztimingtable}
+        [
+            timing/d/background/.style={fill=white},
+            timing/lslope=0.2
+        ]
+            $\mathrm{\overline{CS}}$ & H51{L}H \\
+            SCK     & LL31{T}; 2{[dotted] T}; 17{T} L \\
+            % The better approach is to use pass the counter (\tikztimingcounter{Q}) to a macro,
+            % then print the label from macro. But it turns out tikz-timing will print
+            % the counter value separately, even with an additional macro.
+            % Therefore, it does not work properly.
+            MOSI & [timing/counter/new={char=I, reset char=J, reset type=arg, increment=-1, text format=I}]
+            UJ{7}8{2I}36U \\
+            MOSI & [timing/counter/new={char=A, reset char=R, reset type=arg, increment=-1, text format=D}]
+            17UR{31}8{2A}; [dotted] D [dotted] D{}; R{7}8{2A}2U \\
+    \end{tikztimingtable}%
+    \end{center}
 
-Suppose the instruction is \texttt{0x81}, where only slave 0 is selected. This SPI transcation can be performed by the following code.
-\inputcolorboxminted{firstline=35,lastline=49}{examples/spi.py}
+    Suppose the instruction is \texttt{0x81}, where only slave 0 is selected. This SPI transcation can be performed by the following code.
+    \inputcolorboxminted{firstline=35,lastline=49}{examples/spi.py}
 
-\newpage
 \ordersection{2245 LVDS-TTL}
 
 \finalfootnote

Makefile

@@ -1,4 +1,4 @@
-inputs = 1124 2118-2128 2238 2245 4410-4412 4456 5108 5432 5518-5528 5568 7210
+inputs = 1124 1125 2118-2128 2238 2245 4410-4412 4456 5108 5432 5518-5528 5568 7210
 dir = build
 
 all: $(inputs)

examples/unsorted

@@ -0,0 +1,99 @@
+from artiq.experiment import *
+
+class SineWave(EnvExperiment):
+    def build(self):
+        self.setattr_device("core")
+
+        self.leds = dict()
+        self.ttl_outs = dict()
+        
+        self.dacs_config = dict()
+        self.dac_volt = dict()
+        self.dac_dds = dict()
+        self.dac_trigger = dict()
+        
+        ddb = self.get_device_db()
+        for name, desc in ddb.items():
+            if isinstance(desc, dict) and desc["type"] == "local":
+                module, cls = desc["module"], desc["class"]
+                if (module, cls) == ("artiq.coredevice.ttl", "TTLOut"):
+                    dev = self.get_device(name)
+                    if "led" in name: 
+                        self.leds[name] = dev
+                    else:
+                        self.ttl_outs[name] = dev
+                
+                if (module, cls) == ("artiq.coredevice.shuttler", "Config"):
+                    dev = self.get_device(name)
+                    self.dacs_config[name] = dev
+
+                if (module, cls) == ("artiq.coredevice.shuttler", "Volt"):
+                    dev = self.get_device(name)
+                    self.dac_volt[name] = dev
+                
+                if (module, cls) == ("artiq.coredevice.shuttler", "Dds"):
+                    dev = self.get_device(name)
+                    self.dac_dds[name] = dev
+                
+                if (module, cls) == ("artiq.coredevice.shuttler", "Trigger"):
+                    dev = self.get_device(name)
+                    self.dac_trigger[name] = dev
+                
+        
+        self.leds = sorted(self.leds.items(), key=lambda x: x[1].channel)
+        self.ttl_outs = sorted(self.ttl_outs.items(), key=lambda x: x[1].channel)
+
+        self.dacs_config = sorted(self.dacs_config.items(), key=lambda x: x[1].channel)
+        self.dac_volt = sorted(self.dac_volt.items(), key=lambda x: x[1].channel)
+        self.dac_dds = sorted(self.dac_dds.items(), key=lambda x: x[1].channel)
+        self.dac_trigger = sorted(self.dac_trigger.items(), key=lambda x: x[1].channel)
+        
+
+    @kernel
+    def set_dac_config(self, config):
+        config.set_config(0xFFFF)
+
+    @kernel
+    def set_test_dac_volt(self, volt):
+        a0 = 0
+        a1 = 0
+        a2 = 0
+        a3 = 0
+        volt.set_waveform(a0, a1, a2, a3)
+
+
+    @kernel
+    def set_test_dac_dds(self, dds):
+        b0 = 0x0FFF 
+        b1 = 0
+        b2 = 0
+        b3 = 0
+        c0 = 0
+        c1 = 0x147AE148 # Frequency = 10MHz
+        c2 = 0
+        dds.set_waveform(b0, b1, b2, b3, c0, c1, c2)
+    
+    @kernel
+    def set_dac_trigger(self, trigger):
+        trigger.trigger(0xFFFF)
+
+    @kernel
+    def run(self):
+        self.core.reset()
+
+        self.core.break_realtime()
+        t = now_mu() - self.core.seconds_to_mu(0.2)
+        while self.core.get_rtio_counter_mu() < t:
+            pass
+
+        for dac_config_name, dac_config_dev in self.dacs_config:
+            self.set_dac_config(dac_config_dev)
+
+        for dac_volt_name, dac_volt_dev in self.dac_volt:
+            self.set_test_dac_volt(dac_volt_dev)
+
+        for dac_dds_name, dac_dds_dev in self.dac_dds:
+            self.set_test_dac_dds(dac_dds_dev) 
+
+        for dac_trigger_name, dac_trigger_dev in self.dac_trigger:
+             self.set_dac_trigger(dac_trigger_dev)

preamble.tex

@@ -43,16 +43,24 @@
 BOMs) can be found in detail at the repositories \url{#3} and \url{#4}.
 }
 
-\newcommand*{\ordersection}[1]{
-\section{Ordering Information}
-To order, please visit \url{https://m-labs.hk} and choose #1 in the ARTIQ/Sinara hardware selection tool. Cards can be ordered as part of a fully-featured ARTIQ/Sinara crate or standalone through the 'Spare cards' option. Otherwise, orders can also be made by writing directly to \url{mailto:sales@m-labs.hk}.
+\newcommand{\sysdescsection}{
+\section{ARTIQ System Description Entry}
+
+ARTIQ/Sinara firmware/gateware is generated according to a JSON system description file, allowing gateware to be specific to and optimized for a certain system configuration.
+    % It isn't possible to use verbatim environments within \newcommand macros
+    % so the minted colorbox is easier to use directly in each file
 }
 
-\newcommand{\codesection}[1] {
+\newcommand{\codesection}[1]{
 \section{Example ARTIQ Code}
 The sections below demonstrate simple usage scenarios of extensions on the ARTIQ control system. These extensions make use of the resources of the #1. They do not exhaustively demonstrate all the features of the ARTIQ system.
 
-The full documentation for ARTIQ software and gateware, including the guide for its use, is available at \url{https://m-labs.hk/artiq/manual/}. Please consult the manual for details and reference material of the functions and structures used here.
+The full documentation for ARTIQ software and gateware, including guides for their use, is available at \url{https://m-labs.hk/artiq/manual/}. Please consult the manual for details and reference material of the functions and structures used here.
+}
+
+\newcommand*{\ordersection}[1]{
+\section{Ordering Information}
+To order, please visit \url{https://m-labs.hk} and choose #1 in the ARTIQ/Sinara hardware selection tool. Cards can be ordered as part of a fully-featured ARTIQ/Sinara crate or standalone through the 'Spare cards' option. Otherwise, orders can also be made by writing directly to \url{mailto:sales@m-labs.hk}.
 }
 
 \newcommand*{\finalfootnote}{

shared/coredevice.tex

@@ -0,0 +1,119 @@
+\newcommand{\spectable} {
+    \begin{table}[h]
+        \centering
+        \begin{threeparttable}
+        \caption{Recommended Operating Conditions}
+        \begin{tabularx}{0.85\textwidth}{l | c c c | c | X}
+            \thickhline
+            \textbf{Parameter} & \textbf{Min.} & \textbf{Typ.} & \textbf{Max.} &
+            \textbf{Unit} & \textbf{Conditions} \\
+            \hline
+            Clock input & & & & &\\
+            \hspace{3mm} Input frequency & & 125 & & MHz & Si5324 synthesizer bypassed \\
+            \cline{2-6}
+            % 100R termination & 100/350/600 mV differential input after the transformer.
+            & \multicolumn{3}   {c|}{10/80/100/125} & MHz & RTIO clock synthesized from input \\
+            \cline{2-6}
+            \hspace{3mm} Power & -9 & 1.5 & 5.5 & dBm & \\
+            \hline
+            Power supply rating & \multicolumn{4}{c|}{12V, 5A} & \\
+            \thickhline
+        \end{tabularx}
+        \end{threeparttable}
+        \end{table}
+
+    Power is to be supplied either through the barrel connector in the front panel (size 5.5 mm OD, 2.5 mm ID) or the Molex connector at the back of the card (compatible with e.g. Sinara 1106 EEM AC Power Module). It is passed on to daughtercards through the EEM connections. Locking barrel connectors are supported.
+}
+
+\newcommand{\artiqsection} {
+    \section{Firmware/ARTIQ}
+
+    ARTIQ is open-source and can be found in the repository \url{https://github.com/m-labs/artiq}. Orders of Sinara hardware are normally preflashed with suitable firmware and gateware binaries. Long-term support for ARTIQ systems can also be purchased, including updated binaries through AFWS (the ARTIQ Firmware Service).
+}
+
+\newcommand{\noteondrtio}[1]{
+
+    \subsection{Note on distributed RTIO (DRTIO)}
+
+    DRTIO is the time and data transfer system which allows ARTIQ RTIO channels to be distributed among several core device carrier boards, synchronized and controlled by a central master device. The system itself is described in more detail in the ARTIQ documentation\footnote{\label{manual-drtio}\url{https://m-labs.hk/artiq/manual/drtio.html}}. Within ARTIQ, core devices, including #1, can take one of three roles:
+    \begin{enumerate}%[topsep=2pt, itemsep=2pt]
+        \item \textbf{Master} \\
+        A DRTIO system must contain one DRTIO master. It controls its own local RTIO channels and the downstream DRTIO satellite(s). It requires a direct network connection to the host machine. It may make downstream connections to satellites.
+        \item \textbf{Satellite} \\
+        Other core devices in a DRTIO system are DRTIO satellites. They require an upstream connection to one other core device, master or satellite, through which communications are carried to the master. They may make further downstream connections to other satellites. They may control their local RTIO channels directly through subkernels or simply pass on communications from the master.
+        \item \textbf{Standalone}\\
+        When run in a non-distributed ARTIQ configuration, with a single central core device but without satellites, that core device is known as standalone.
+    \end{enumerate}
+
+}
+
+\newcommand{\clockingsection}[2]{
+
+    \section{Clock Routing}
+
+    \subsection{Standalone/Master}
+
+    The RTIO clock is typically synthesized by the Si5324 clock multiplier and distributed by the ADCLK948 clock fanout buffer to both the #2 and the MMCX connectors. Alternatively, an external reference can be supplied through the front panel SMA connector. It is then buffered in the #2 and sent to the Si5324 for clock synthesis. #1 supports a set of RTIO clock options:
+
+    \begin{table}[H]
+        \centering
+        \begin{tabular}{|c|c|c|}
+        \hline
+        RTIO frequency           & Configuration          & Clock generation                                                \\ \hline
+        100 MHz                  & \texttt{int\char`_100} & internal crystal oscillator using PLL, 100 MHz output           \\ \hline
+        \multirow{5}{*}{125 MHz} & \texttt{int\char`_125} & internal crystal oscillator using PLL, 125 MHz output (default) \\ \cline{2-3}
+                                & \texttt{ext0\char`_synth0\char`_10to125}  & external 10 MHz reference using PLL, 125 MHz output             \\ \cline{2-3}
+                                & \texttt{ext0\char`_synth0\char`_80to125}  & external 80 MHz reference using PLL, 125 MHz output             \\ \cline{2-3}
+                                & \texttt{ext0\char`_synth0\char`_100to125} & external 100 MHz reference using PLL, 125 MHz output            \\ \cline{2-3}
+                                & \texttt{ext0\char`_synth0\char`_125to125} & external 125 MHz reference using PLL, 125 MHz output            \\ \hline
+        \end{tabular}
+    \end{table}
+
+    The clock synthesizer may also be bypassed, using the \texttt{ext0\char`_bypass} option, which will accept a RTIO clock directly supplied to the SMA connector. The resulting signal is then routed to both the RTIO system and downstream satellites.
+
+    Clocking options in a running system should be configured by setting the value of the \texttt{rtio\char`_clock} key to the desired configuration through the ARTIQ \texttt{artiq\char`_coremgmt} command. For example, a RTIO frequency of 125MHz will be synthesized from an external 10 MHz signal after issuing the following command:
+
+    \begin{center}
+    \texttt{artiq\_coremgmt config write -s rtio\_clock ext0\_synth0\_10to125}
+    \end{center}
+
+    and rebooting.
+
+    \subsection{Satellite}
+    The RTIO clock is recovered from the SFP transceiver connected to the upstream device. The resulting signal is then cleaned up by the Si5324 and routed to both the RTIO system and downstream satellites.
+
+    \subsection{WRPLL}
+
+    #1 can be configured to use WRPLL, a clock recovery method making use of White Rabbit's DDMTD (Digital Dual Mixer Time Difference) and the card's Si549 oscillators, both to lock the main RTIO clock and to lock satellite clocks to master.
+}
+
+\newcommand{\coresysdesc}{ % again including the minted JSON snippet through a macro isn't practical
+
+    where the \texttt{peripherals} list contains the corresponding entries for peripherals (daughtercards) in use.
+
+    For all accepted keys and values, see the JSON schema \texttt{coredevice\_generic.schema.json} in the ARTIQ repository.\footnote{\url{https://github.com/m-labs/artiq/blob/release-8/artiq/coredevice/coredevice_generic.schema.json}}.
+}
+
+\newcommand{\coredevicecode}[1] {
+    \codesection{#1}
+
+    \subsection{Direct Memory Access (DMA)}
+
+    Instead of directly emitting RTIO events, sequences of RTIO events can be recorded in advance and stored in the local SDRAM. The event sequence can then be replayed at a specified timestamp. This is of special advantage in cases where RTIO events are too closely placed to be generated as they are executed, as events can be replayed at a higher speed than the on-FPGA CPU alone is capable of.
+
+    The following example records an LED event sequence and replays it twice consecutively using \texttt{CoreDMA}. When run, the LED should blink twice.
+
+    \inputcolorboxminted{firstline=10,lastline=29}{examples/dma.py}
+
+    Stored waveforms can be referenced and replayed in different kernels, but cannot be retrieved and must be regenerated if the core device is rebooted.
+
+    \subsection{Dataset manipulation with core device cache}
+    Experiments may require values computed or found in previously executed kernels. To avoid invoking an RPC or sacrificing the pre-computation in \texttt{prepare()} stage, data can be stored in the core device cache.
+
+    The following code snippets describe two experiments, in which the data from the first experiment is cached. The data is then retrieved and printed in hexadecimal form in the second experiment.
+
+    \inputcolorboxminted{firstline=9,lastline=16}{examples/cache.py}
+    \inputcolorboxminted{firstline=24,lastline=35}{examples/cache.py}
+
+    Similar to DMA, cached data is no longer retrievable once the core device has been rebooted.
+}