tiny-xo2/doc/tiny-xo2-documentation.tex

% Notes:
% http://www.ti.com/lit/ds/symlink/tlv1117.pdf
% http://www.latticesemi.com/~/media/LatticeSemi/Documents/UserManuals/MQ/ProgrammingCableUsersGuide.pdf?document_id=143
% http://www.latticesemi.com/~/media/LatticeSemi/Documents/ApplicationNotes/MO/MachXO2ProgrammingandConfigurationUsageGuide.pdf?document_id=39085
% http://www.latticesemi.com/~/media/LatticeSemi/Documents/DataSheets/MachXO23/MachXO2FamilyDataSheet.pdf?document_id=38834

\documentclass[openany,oneside]{scrbook}
\usepackage[printonlyused]{acronym}
\usepackage[
pdftitle={Tiny-XO2 Development Kit},
pdfauthor={Markus Koch},
pdfsubject={Tiny-XO2 Development Kit},
pdfcreator={pdflatex, LaTeX with KOMA-Script},
pdfpagemode=UseOutlines,
pdfdisplaydoctitle=true,
pdflang=en,
%plainpages=false,
]{hyperref}
\hypersetup{
	colorlinks=true,
	hidelinks=true,
	linkcolor=blue,
	citecolor=green,
	%filecolor,
	%menucolor=black,
	%urlcolor=cyan,
	bookmarksnumbered=true
}
\usepackage{booktabs}
\usepackage{multirow}
\usepackage{graphicx}
\usepackage{color}
\usepackage{pdfpages}
\usepackage{pdflscape}
\usepackage[american]{babel}
\usepackage[babel,german=quotes]{csquotes}
\usepackage[
backend=biber,
style=numeric,
natbib,
bibencoding=utf8
%apabackref=true,
]{biblatex}
\addbibresource{lit.bib}
\DeclareLanguageMapping{american}{american-apa}

\usepackage{caption}
\captionsetup{labelfont=bf}

%\usepackage{draftwatermark}
%\SetWatermarkScale{5}
%\SetWatermarkLightness{0.94}

\title{Tiny-XO2 Development Kit}
\author{Markus Koch $\langle$markus@notsyncing.net$\rangle$}
\publishers{\centering\includegraphics[width=.55\textwidth]{img/coverpage.png}}

\setlength{\parindent}{0cm}
\setlength{\parskip}{1em}

\begin{document}

\maketitle

\include{acro}
\acused{led}

\tableofcontents

\chapter{Introduction}
The Tiny-XO2 is a small, versatile and cost-effective development platform for the Lattice MachXO2 \acp{fpga}.

In addition to the \ac{fpga}, it provides a \ac{usb} to \ac{uart} converter and a crystal to include the basic set of components for any \ac{fpga} design.


\chapter{Hardware}
This chapter explains all available hardware functions.

\section{Overview}
Figure \ref{fig:overview} and Table \ref{tab:overview} show an overview of all the functions of the board.

\begin{figure}[h]
	\centering
	\includegraphics[width=\textwidth]{img/overview.pdf}
	\caption{Board overview}
	\label{fig:overview}
\end{figure}

\begin{table}[h]
	\caption{Board function list}
	\label{tab:overview}
	\centering
	\begin{tabular}{ll} \toprule
		1 & \acs{jtag} programming header \\
		2 & Lattice LCMXO2-1200HC \acs{fpga} \\
		3 & Power \ac{led} (Orange) \\
		4 & \acs{uart} \acs{tx} (Board $\rightarrow$ PC) \acs{led} (Red) \\
		5 & \acs{uart} \acs{rx} (PC $\rightarrow$ Board) \acs{led} (Green) \\
		6 & \acs{usb} socket for \acs{uart} and power \\
		\midrule
		7 & \acs{io} headers \\
		8 & 12 MHz crystal oscillator for \acs{fpga} and \acs{usb}-to-\acs{uart} converter \\
		9 & CH340G \acs{usb} to \acs{uart} converter \\
		10 & 5 V to 3.3 V \ac{ldo} \\ \bottomrule
	\end{tabular}
\end{table}

\section{Power Supply}
\label{power}
The board can be powered either via \ac{usb} or using the \texttt{VB} pin on pin header \texttt{J3}. The input voltage can range from 5 V to 15 V \parencite[page 4]{tlv1117}. A diode between the \ac{usb} jack and the \texttt{VB} pin prevents backfeeding of current into the \ac{usb} connection.

The \texttt{3V} pins on the pin headers can be used to supply the on-board generated 3.3 V to supporting circuitry. The maximum current to be drawn from these pins is 500 mA\footnote{The maximum current of the AP1117 voltage regulator is 800 mA\parencite[page 4]{tlv1117}. Watch the temperature of \texttt{U1} when drawing high amounts of current.}.

All \ac{io} pins on header \texttt{J3} use the voltage on pin \texttt{VX} as bank voltage. By populating \texttt{R9} with a zero Ohm resistor, the bank can be connected to the on-board 3.3 V supply. In this case, \texttt{VX} becomes a normal \texttt{3V} pin. See chapter \ref{ioheaders} for more details.

\section{\acs{fpga}}
\label{fpga}
The \ac{fpga} present on the board is a Lattice LCMXO2-1200HC-\emph{4}SG32C or LCMXO2-1200HC-\emph{6}SG32C.

\begin{table}[h]
	\caption{Main features of the \ac{fpga} \parencite[page 3]{machxo2family}}
	\label{tab:fpgafeatures}
	\centering
	\begin{tabular}{ll} \toprule
		\textbf{Property} & \textbf{Value} \\ \midrule
		\ac{io}			& 21* \\
		LUTs			& 1280 \\
		Distributed RAM	& 10 kbits \\
		EBR SRAM		& 64 kbits \\
		User flash		& 64 kbits \\
		Hard IPs		& 2x I$^2$C, 1x SPI, 1x Timer / Counter, 1x PLL \\ \bottomrule
	\end{tabular}
	\\ \textit{* Not all \acp{io} may be usable, see chapter \ref{ioheaders}.}
\end{table}

Depending on the version of the board, either speedgrade 4 or 6 is installed. Check the marking on the chip to determine which version applies.


\section{\acs{uart} and \acsp{led}}
\label{uart}
The board features a CH340G \ac{usb}-to-\ac{uart} converter. Its \ac{tx} line is connected to pin \texttt{21}, the \ac{rx} line is connected to pin \texttt{20}. Pin \texttt{23} is connected to the \ac{dtr} signal from the chip, which is pulled low as soon as the terminal is opened on the PC.

See the markings on the board for a quick reference of the pin functions.

Additionally, the \ac{rx} and \ac{tx} lines have an \ac{led} connected in parallel. Should a specific \ac{led} or \ac{uart} function be not wanted, refer to table \ref{tab:uartresistors} to see how to disable individual features.

\begin{table}[h]
	\caption{Resistors to disable \ac{uart} functions}
	\label{tab:uartresistors}
	\centering
	\begin{tabular}{cll} \toprule
		\textbf{Resistor}	& \textbf{Description}	\\ \midrule
		R6					& \ac{uart} \ac{tx}	 \\
		R7					& \ac{uart} \ac{rx}	 \\
		R8					& \ac{uart} \ac{dtr}	 \\
		\midrule
		R4					& \ac{tx} \ac{led}	 \\
		R5					& \ac{rx} \ac{led}	 \\ \bottomrule
	\end{tabular}
\end{table}

\section{Crystal Oscillator}
\label{crystal}
The board features a 12 MHz crystal oscillator. It supplies the clock to the \ac{usb}-to-\ac{uart} converter and is also connected to pin \texttt{28} of the \ac{fpga}. If the 12 MHz clock signal is not needed on the \ac{fpga}, resistor \texttt{R2} can be removed to free pin \texttt{28} as a general purpose \ac{io} pin.

\section{\acs{io} Headers}
\label{ioheaders}
The \ac{io} headers break out all available \ac{io} pins of the \ac{fpga}. The pin number is marked next to each pin on the board.

Header \texttt{J3} has no special functions and uses \texttt{VX} as bank voltage. This voltage can be tied to the 3.3 V supply of the board by installing a zero ohm resistor for component \texttt{R9}.

Header \texttt{J4} has special functions assigned to most of its pins. Refer to Table \ref{tab:iofunctions} for a comprehensive list. In order to use these pins as general purpose \ac{io} pins, refer to the respective chapter. All \ac{io} pins on header \texttt{J4} use 3.3 V as bank voltage.

\begin{table}[h]
	\caption{\acs{io} pin special functions}
	\label{tab:iofunctions}
	\centering
	\begin{tabular}{clll} \toprule
		\textbf{Function} & \textbf{Pin}				& \textbf{Name}				& \textbf{Note} \\ \midrule
		\acs{jtag} multiplex & \texttt{26}					& $\overline{\textrm{JTAGENB}}$							& See chapter \ref{progopt:multiplex} \\ \midrule
		
		\multirow{4}{3em}{\acs{jtag}} 	& \texttt{29}	& TMS	& \multirow{4}{8em}{See chapter \ref{progopt:always}} \\
										& \texttt{30}	& TCK	\\
										& \texttt{31}	& TDI	\\
										& \texttt{01}	& TDO	\\ \midrule
					
		\multirow{3}{3em}{\acs{uart}}	& \texttt{20}	& \acs{rx}	& \multirow{3}{8em}{See chapter \ref{uart}} \\
										& \texttt{21}	& \acs{tx}	\\
										& \texttt{23}	& \ac{dtr}	\\ \midrule
		
		Clock & \texttt{28}				& 12 MHz clock			& See chapter \ref{crystal} \\ \bottomrule
	\end{tabular}
\end{table}

\chapter{Software Configuration}
\section{Comparison}
\begin{table}[h]
	\caption{Comparison of configuration methods}
	\label{tab:confcompare}
	\centering
	\begin{tabular}{lcl} \toprule
		\textbf{Type}				& \textbf{Available \acs{io}}	& \textbf{Note} \\ \midrule
		Always-active \acs{jtag} 	& \texttt{18}					& Advanced debugging possible\\
		Multiplexed \acs{jtag} 		& \texttt{21}					& Special consideration for 4 pins \\
		Bootloader / None 			& \texttt{22}					& Chip can not be recovered on error\\ \bottomrule
	\end{tabular}
\end{table}

\section{Programming Options}
\label{progopt}

\subsection{Always-active \acs{jtag}}
\label{progopt:always}
This is the simplest of all configuration methods. It is supported by any Lattice programmer, including the FTDI FTxxxx based ones.

To use this method, no special configuration needs to be applied in the Lattice Diamond software. The programming preferences in the \textit{global preferences} in the spreadsheet view should look like this \parencite{machxo2conf}:
\begin{table}[h]
	\caption{Preferences for always-active \ac{jtag} mode}
	\label{tab:prefmux}
	\centering
	\begin{tabular}{lcl} \toprule
		\textbf{Name}				& \textbf{Value} \\ \midrule
		JTAG\_PORT					& ENABLE\\
		MUX\_CONFIGURATION\_PORTS	& DISABLE \\ \bottomrule
	\end{tabular}
\end{table}

The following connections need to be made between the programmer and the \ac{jtag} header \texttt{J2}: TDO (\texttt{TO}), TDI (\texttt{TI}), TCK (\texttt{TC}), TMS (\texttt{TM}).

Pins \texttt{29}, \texttt{30}, \texttt{31} and \texttt{01} are not available as user \acp{io} in this configuration. All other pins are available as normal user \acp{io}.

\subsection{Multiplexed \acs{jtag}}
\label{progopt:multiplex}
This configuration allows to use the \ac{jtag} pins as normal user \ac{io} as long as some parameters are kept in mind.

In this mode, the function of pins \texttt{29}, \texttt{30}, \texttt{31} and \texttt{01} is switched using pin \texttt{26} (\texttt{EN}). This pin needs to be pulled low to enable \ac{jtag} mode. This can either be done manually before each programming operation or by using the \texttt{PROGRAMN} pin available on Lattice programmers. To make the automatic switchover work, the following settings need to be applied in the Diamond software \parencite{progcable}:

\begin{figure}[h]
	\centering
	\includegraphics[width=.5\textwidth]{img/jtagmuxset.png}
	\caption{\ac{jtag} settings for automatic pin multiplexing}
	\label{fig:jtagmuxset}
\end{figure}

To enable this mode, the following settings need to be configured in the \textit{global preferences} in the spreadsheet view in Lattice Diamond:
\begin{table}[h]
	\caption{Preferences for multiplexed \ac{jtag} mode}
	\label{tab:prefmux}
	\centering
	\begin{tabular}{lcl} \toprule
		\textbf{Name}				& \textbf{Value} \\ \midrule
		JTAG\_PORT					& DISABLE \\
		MUX\_CONFIGURATION\_PORTS	& ENABLE \\ \bottomrule
	\end{tabular}
\end{table}

When programming the \ac{fpga} in circuit, the user needs to ensure that all \ac{jtag} lines are high-Z during programming (when \texttt{26} (\texttt{EN}) is low). Also, the \ac{jtag} bit patterns should not affect any components attached to the \ac{jtag} pins during a programming operation.

The following connections need to be made between the programmer and the \ac{jtag} header \texttt{J2}: TDO (\texttt{TO}), TDI (\texttt{TI}), TCK (\texttt{TC}), TMS (\texttt{TM}), PROGRAMN (\texttt{EN}).

Pin \texttt{26} is not available as user \ac{io} in this configuration. Care needs to be taken when selecting which components to connect to pins \texttt{29}, \texttt{30}, \texttt{31} and \texttt{01}. All other pins are available as normal user \acp{io}.

\subsection{\acs{uart} Bootloader}
\label{progopt:bootloader}
\textit{NYI. TODO.}

{\color{red}WARNING: Setting these parameters will \textbf{permanently} disable the \ac{jtag} port. This might render the device unusable. Only apply this if you really know what you are doing.}

\begin{table}[h]
	\caption{Preferences for bootloader mode}
	\label{tab:prefmux}
	\centering
	\begin{tabular}{lcl} \toprule
		\textbf{Name}				& \textbf{Value} \\ \midrule
		JTAG\_PORT					& DISABLE \\
		MUX\_CONFIGURATION\_PORTS	& DISABLE \\ \bottomrule
	\end{tabular}
\end{table}

All \ac{io} pins are available as user \acp{io}.


\chapter{Appendix}
\section{Version History}
\begin{table}[h]
	\caption{Version history}
	\label{tab:versionhistory}
	\centering
	\begin{tabular}{ll} \toprule
		\textbf{Version}				& \textbf{Comment} \\ \midrule
		2017-11-16 & Editorial changes \\
		2017-11-10 & Initial draft \\ \bottomrule
	\end{tabular}
\end{table}

\section{Bibliography}
\printbibliography[heading=none]

\section{Schematic}
See next page.
\begin{landscape}
	\includepdf[angle=90,pages={1-}]{res/schematic.pdf}
\end{landscape}

\end{document}