% 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{xcolor}
\usepackage{adjustbox}
\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}

\newcommand\hwmodSym{%
	\makebox[1.4em][c]{%
		\makebox[0pt][c]{\raisebox{.1em}{\small!}}%
		\makebox[0pt][c]{\color{blue}\Large$\bigtriangleup$}}}%
	
\newcommand\WarningSym{%
	\makebox[1.4em][c]{%
		\makebox[0pt][c]{\raisebox{.1em}{\small!}}%
		\makebox[0pt][c]{\color{red}\Large$\bigtriangleup$}}}%

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

\newcommand{\hwmod}[1]{
	\begin{center}
		\adjustbox{minipage=\textwidth,cfbox=blue}{
				\begin{center}
					\hwmodSym \textbf{Hardware Modification}\hwmodSym
				\end{center}
				#1
		}
	\end{center}
}
\newcommand{\Warning}[1]{
	\begin{center}
		\adjustbox{minipage=\textwidth,cfbox=red}{
			\begin{center}
				\WarningSym \textbf{Warning}\WarningSym
			\end{center}
			#1
		}
	\end{center}
}

\begin{document}

\maketitle

\include{acro}
\acused{led}

\tableofcontents

\chapter{Introduction}
The Tiny-XO2 is a small, versatile and cost-effective development platform for 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.

This manual applies to hardware revision 01. The latest version can be found online at \\ \url{https://l.notsyncing.net/tinyxo2}

\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. It may range from 1.2 V to 3.3 V \parencite[page 8]{ioguide}. 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.

\hwmod{If a 2.5 V supply voltage is required for all \ac{io} pins, the main voltage regulator \texttt{U1} can be replaced with a 1117-2.5 2.5 V voltage regulator. The \ac{fpga} will continue to function normally in this case. When doing this, all \texttt{3V} pins carry 2.5 V. \texttt{VX} may be supplied with up to 3.3 V. \textbf{The CH340G \ac{usb}-to-serial converter will stop working in this configuration} and needs to be removed from the board.}

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

\paragraph{Reset on terminal.} By default, the \texttt{DTR} pin is pulled low by the CH340 as soon as the terminal is opened on the PC and remains high while it is closed. This high-to-low transition can be detected using an edge detector inside the \ac{fpga} to generate a reset for the rest of the design.

\hwmod{If only a short pulse is desired when the terminal is opened, \texttt{R8} should be exchanged with a 100 nF capacitor and the internal pull-up of the \ac{fpga} must be enabled. Now, each time the terminal is opened on the PC, the DTR line on the \ac{fpga} will go low for a few ms.}

\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. A higher frequency for the design can be generated using the \ac{pll} inside the \ac{fpga}.

\hwmod{If another base frequency is required, the crystal oscillator on the back (\texttt{U4}) can be exchanged with another value. \textbf{The CH340G \ac{usb}-to-\ac{uart} converter will stop working in this configuration} and needs to be removed from the board.}

\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 either by installing a zero ohm resistor for component \texttt{R9} or by installing a jumper between the \texttt{VX} and \texttt{3V} pin. Refer to chapter \ref{power} for more information on \ac{io} voltages.

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.

Note that the \ac{jtag} pins are connected in parallel to the \ac{jtag} header \texttt{J2} and the corresponding pins on \texttt{J4}.

\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{32}	& 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}
The MachXO2 devices can be programmed from the active design. This allows the user to entirely disable all external programming interfaces which makes all \ac{io} pins available to the user logic.

At the current point in time, this functionality has not been implemented.

\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{Errata}
\section*{Hardware Revision 01}
\paragraph{TLV1117-33 decoupling.}
The board is missing the 10+ $\mu F$ capacitor on the output of the 1117-3.3 voltage regulator (\texttt{U1}). This might cause instability with certain devices. This problem can be easily solved by installing a 10 $\mu F$ 0805 capacitor right next to \texttt{C7}. Revision 02 addresses this issue.


\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-27 & DTR usage, 2.5 V mod, errata, editorial changes \\
		2017-11-20 & Fix \ac{jtag} TDI pin number \\
		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}