\documentclass[10pt]{datasheet}
\usepackage{palatino}
\usepackage{textgreek}
\usepackage{minted}
\usepackage{tcolorbox}
\usepackage{etoolbox}

\usepackage[justification=centering]{caption}

\usepackage[utf8]{inputenc}
\usepackage[english]{babel}
\usepackage[english]{isodate}

\usepackage{graphicx}
\usepackage{subfigure}

\usepackage{tikz}
\usepackage{pgfplots}
\usepackage{circuitikz}
\usepackage{pifont}
\usetikzlibrary{calc}
\usetikzlibrary{fit,backgrounds} 

\title{1124 Carrier Kasli 2.0}
\author{M-Labs Limited}
\date{October 2024}
\revision{Revision 2}
\companylogo{\includegraphics[height=0.73in]{artiq_sinara.pdf}}

\begin{document}
\maketitle

\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}
\end{itemize}

\section{Applications}

\begin{itemize}
\item{Run ARTIQ kernels}
\item{Communicate with the host}
\item{Control other Sinara EEM cards}
\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.

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.

% Switch to next column
\vfill\break

\newcommand*{\MyLabel}[3][2cm]{\parbox{#1}{\centering #2 \\ #3}}
\newcommand*{\MymyLabel}[3][4cm]{\parbox{#1}{\centering #2 \\ #3}}
\newcommand{\repeatfootnote}[1]{\textsuperscript{\ref{#1}}}
\newcommand{\inputcolorboxminted}[2]{%
    \begin{tcolorbox}[colback=white]
    \inputminted[#1, gobble=4]{python}{#2}
    \end{tcolorbox}
}

\begin{figure}[h]
    \centering
    \scalebox{1.15}{
    \begin{circuitikz}[european, every label/.append style={align=center}]

        \begin{scope}[]

            % Draw the FPGA
            \draw (0, 0) node[twoportshape, t={FPGA}, circuitikz/bipoles/twoport/height=1.5, circuitikz/bipoles/twoport/width=1.2, scale=1] (fpga) {};

            % External clock for RTIO, west of the FPGA
            \draw [color=white, text=black] (-3.1, 0) node[twoportshape, circuitikz/bipoles/twoport/width=1.2, scale=0.4] (ext_clk) {};
            \node [label=left:\tiny{EXT CLK}] at (-2.65, 0) {};
            \begin{scope}[scale=0.07 , rotate=-90, xshift=0cm, yshift=-40cm]
                \draw (0,0.65) -- (0,3);
                \clip (-1.5,0) rectangle (1.5,1.5);
                \draw (0,0) circle(1.5);
                \clip (-0.8,0) rectangle (0.8,0.8);
                \draw (0,0) circle(0.8);
            \end{scope}
            \draw [-latexslim] (ext_clk) -- (fpga.west);

            % USB Mirco B port with USB-UART converter, north west of the FPGA
            \draw (-3.2, 1.2) node[twoportshape, t={USB Micro B}, circuitikz/bipoles/twoport/width=1.8, scale=0.5, rotate=-90] (usb) {};
            \draw (-2, 1.2) node[twoportshape, t={\MymyLabel{USB-UART}{Converter}}, circuitikz/bipoles/twoport/width=1.8, scale=0.5, rotate=-90] (uart) {};
            \draw [latexslim-latexslim] (usb.north) -- (uart.south);
            \draw [latexslim-latexslim] (uart.north) -- (-1.3, 1.2) -- (-1.3, 0.4) -- (-0.85, 0.4);

            % 4-SFP cage, south west of the FPGA
            \draw (-3.4, -0.8) node[twoportshape, t={SFP 0}, circuitikz/bipoles/twoport/height=0.6, circuitikz/bipoles/twoport/width=1, scale=0.5, rotate=-90] (sfp0) {};
            \draw (-3, -0.8) node[twoportshape, t={SFP 1}, circuitikz/bipoles/twoport/height=0.6, circuitikz/bipoles/twoport/width=1, scale=0.5, rotate=-90] (sfp1) {};
            \draw (-3.4, -1.5) node[twoportshape, t={SFP 2}, circuitikz/bipoles/twoport/height=0.6, circuitikz/bipoles/twoport/width=1, scale=0.5, rotate=-90] (sfp2) {};
            \draw (-3, -1.5) node[twoportshape, t={SFP 3}, circuitikz/bipoles/twoport/height=0.6, circuitikz/bipoles/twoport/width=1, scale=0.5, rotate=-90] (sfp3) {};
            \draw [latexslim-latexslim] (-2.8, -1.15) -- (-2.2, -1.15) -- (-2.2, -0.4) -- (-0.85, -0.4);

            % Clock signal cleaning path, south of the FPGA,
            % clock signal loop from the south west to the south east
            \draw (-0.8, -2.1) node[twoportshape, t={\MymyLabel{Clock}{Multiplier}}, circuitikz/bipoles/twoport/width=1.6, scale=0.5, rotate=-90] (clk_mul) {};
            \draw (0.8, -2.1) node[twoportshape, t={\MymyLabel{Clock}{Buffer}}, circuitikz/bipoles/twoport/width=1.6, scale=0.5, rotate=-90] (clk_buf) {};
            \draw [-latexslim] (-0.85, -0.8) -- (-1.6, -0.8) -- (-1.6, -1.9) -- (-1.05, -1.9);
            % % A dashed path from EXT CLK to CDR CLK
            \draw [dashed, -latexslim] (fpga.west) -- (-0.6, 0) -- (-0.6, -0.8) -- (-0.85, -0.8);
            % % Internal oscillator for the RTIO clock
            \draw (-2.2, -2.3) node[twoportshape, t={OSC}, circuitikz/bipoles/twoport/width=1, scale=0.5] (rtio_osc) {};
            \draw [-latexslim] (rtio_osc.east) -- (-1.05, -2.3);
            \draw [-latexslim] (clk_mul.north) -- (clk_buf.south);
            \draw [-latexslim] (clk_buf.north) -- (1.6, -2.1) -- (1.6, -0.4) -- (0.85, -0.4);
            % % MMCX output
            \draw [color=white, text=black] (2.75, -1.05) node[twoportshape, circuitikz/bipoles/twoport/width=1.2, scale=0.4] (mmcx0) {};
            \draw [color=white, text=black] (2.75, -1.4) node[twoportshape, circuitikz/bipoles/twoport/width=1.2, scale=0.4] (mmcx1) {};
            \draw [color=white, text=black] (2.75, -1.75) node[twoportshape, circuitikz/bipoles/twoport/width=1.2, scale=0.4] (mmcx2) {};
            \draw [color=white, text=black] (2.75, -2.1) node[twoportshape, circuitikz/bipoles/twoport/width=1.2, scale=0.4] (mmcx3) {};
            \node [label=right:\tiny{MMCX 0}] at (2.3, -1.05) {};
            \node [label=right:\tiny{MMCX 1}] at (2.3, -1.4) {};
            \node [label=right:\tiny{MMCX 2}] at (2.3, -1.75) {};
            \node [label=right:\tiny{MMCX 3}] at (2.3, -2.1) {};
            \begin{scope}[scale=0.07 , rotate=90, xshift=-30cm, yshift=-35cm]
                \draw (0,0.65) -- (0,3);
                \clip (-1.5,0) rectangle (1.5,1.5);
                \draw (0,0) circle(1.5);
                \clip (-0.8,0) rectangle (0.8,0.8);
                \draw (0,0) circle(0.8);
            \end{scope}
            \begin{scope}[scale=0.07 , rotate=90, xshift=-25cm, yshift=-35cm]
                \draw (0,0.65) -- (0,3);
                \clip (-1.5,0) rectangle (1.5,1.5);
                \draw (0,0) circle(1.5);
                \clip (-0.8,0) rectangle (0.8,0.8);
                \draw (0,0) circle(0.8);
            \end{scope}
            \begin{scope}[scale=0.07 , rotate=90, xshift=-20cm, yshift=-35cm]
                \draw (0,0.65) -- (0,3);
                \clip (-1.5,0) rectangle (1.5,1.5);
                \draw (0,0) circle(1.5);
                \clip (-0.8,0) rectangle (0.8,0.8);
                \draw (0,0) circle(0.8);
            \end{scope}
            \begin{scope}[scale=0.07 , rotate=90, xshift=-15cm, yshift=-35cm]
                \draw (0,0.65) -- (0,3);
                \clip (-1.5,0) rectangle (1.5,1.5);
                \draw (0,0) circle(1.5);
                \clip (-0.8,0) rectangle (0.8,0.8);
                \draw (0,0) circle(0.8);
            \end{scope}

            \draw [-latexslim] (1.6, -1.05) -- (mmcx0);
            \draw [-latexslim] (1.6, -1.4) -- (mmcx1);
            \draw [-latexslim] (1.6, -1.75) -- (mmcx2);
            \draw [-latexslim] (1.6, -2.1) -- (mmcx3);

            % Memory modules, north of the FPGA
            \draw (-0.55, 2.4) node[twoportshape, t={\MymyLabel{SPI}{Flash}}, circuitikz/bipoles/twoport/width=1.3, scale=0.5] (spi_flash) {};
            \draw (0.55, 2.4) node[twoportshape, t={SDRAM}, circuitikz/bipoles/twoport/width=1.3, scale=0.5] (sdram) {};
            \draw [latexslim-latexslim] (spi_flash.south) -- (-0.55, 1.05);
            \draw [latexslim-latexslim] (sdram.south) -- (0.55, 1.05);

            % EEM connectors x12, horizontally located at y=0.4
            \draw (2, 1.8) node[twoportshape, t={EEM Port 0}, circuitikz/bipoles/twoport/width=1.6, scale=0.5, rotate=-90] (eem0) {};
            \node at (2.4, 1.8)[circle,fill,inner sep=0.7pt]{};
            \node at (2.6, 1.8)[circle,fill,inner sep=0.7pt]{};
            \node at (2.8, 1.8)[circle,fill,inner sep=0.7pt]{};
            \draw (3.2, 1.8) node[twoportshape, t={EEM Port 11}, circuitikz/bipoles/twoport/width=1.6, scale=0.5, rotate=-90] (eem11) {};
            \draw [decorate, decoration = {brace}] (3.4, 1.1) --  (1.8, 1.1);
            \draw [latexslim-latexslim] (2.6, 1) -- (2.6, 0.4) -- (0.85, 0.4);
        \end{scope}
    \end{circuitikz}
    }

    \caption{Simplified Block Diagram}
\end{figure}

\begin{figure}[hbt!]
    \centering
    \includegraphics[height=2in]{photo1124.jpg}
    \caption{Kasli 2.0 card}
\end{figure}


\begin{figure}[hbt!]
    \centering
    \includegraphics[angle=90,height=0.9in]{Kasli_FP.pdf}
    \caption{Kasli 2.0 front panel}
\end{figure}

% For wide tables, a single column layout is better. It can be switched
% page-by-page.
\onecolumn

\section{Source}

Kasli 2.0, like all the Sinara hardware family, is open-source hardware, and design files (schematics, PCB layouts, BOMs) can be found in detail at the repository \url{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.

\section{FPGA}

Kasli 2.0 features an XC7A100T-3FGG484E Xilink 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.

\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.
\end{enumerate}

When run in a non-distributed ARTIQ configuration, with a single central core device but no satellites, that core device is instead known as \textbf{standalone.}

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

\subsection{Upstream connection}

A Kasli 2.0 board must acquire an upstream connection through the \texttt{SFP0} slot.

\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}

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

\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}

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.

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

\newpage

\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 on the Kasli 2.0 1124 carrier board. 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 on the functions and structures used here.

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

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

\section{Ordering information}
To order, please visit \url{https://m-labs.hk} and select 1124 Carrier Kasli 2.0 in the ARTIQ/Sinara crate configuration tool. Cards may also be ordered separately by writing to \url{mailto:sales@m-labs.hk}.

\section*{}
\vspace*{\fill}

\begin{footnotesize}
Information furnished by M-Labs Limited is provided in good faith in the hope that it will be useful. However, no responsibility is assumed by M-Labs Limited for its use. Specifications may be subject to change without notice.
\end{footnotesize}

\end{document}
