Add documentation draft

This commit is contained in:
Markus Koch 2017-11-10 22:26:46 +01:00
parent 18151985c0
commit 9ee7dce2c8
10 changed files with 366 additions and 0 deletions

12
doc/.gitignore vendored Normal file
View File

@ -0,0 +1,12 @@
*.aux
*~
*.bbl
*.bcf
*.blg
*.log
*.run.xml
*.synctex.gz
*.toc
*.pdf
*.svg
!res/*

25
doc/acro.tex Normal file
View File

@ -0,0 +1,25 @@
% Sort using emacs:
% http://rtime.felk.cvut.cz/~sojka/blog/sorting-latex-acronyms-in-emacs/
%I press C-up to go to \begin{ and then left. This moves me at the end of the
% elisp expression.
% Press C-x C-e (eval-last-sexp) and the list is sorted!
\chapter*{List of Abbreviations}
\addcontentsline{toc}{chapter}{List of Abbreviations}
% Sort acronyms: (let ((sort-fold-case t)) (sort-regexp-fields nil "^[[:space:]]*\\\\acro\{\\([^}]*\\)\}.*$" "\\1" (point-min) (point-max)))
% \acro{} {}
\begin{acronym}[TDMA]
%
\acro{fpga} [FPGA] {field-programmable gate array}
\acro{uart} [UART] {universal asynchronous receiver / transmitter}
\acro{jtag} [JTAG] {Joint Test Action Group}
\acro{usb} [USB] {universal serial bus}
\acro{led} [LED] {light emitting diode}
\acro{io} [I/O] {input / output}
\acro{ldo} [LDO] {low-dropout regulator}
\acro{rx} [RX] {receive}
\acro{tx} [TX] {transmit}
\acro{} [] {}
\acro{} [] {}
\end{acronym}

BIN
doc/img/coverpage.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 632 KiB

BIN
doc/img/jtagmuxset.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

15
doc/img/makepdf.sh Executable file
View File

@ -0,0 +1,15 @@
#!/bin/bash
for file in ./*.dia; do
p=${file%.dia}
p=${p##*/}
outfile="$p.svg"
dia --export=$outfile $file
done
for file in ./*.svg; do
p=${file%.svg}
p=${p##*/}
outfile="$p.pdf"
inkscape -D -z --file="$file" --export-pdf="$outfile" #--export-latex
done

BIN
doc/img/overview.dia Normal file

Binary file not shown.

BIN
doc/img/overview.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 71 KiB

45
doc/lit.bib Normal file
View File

@ -0,0 +1,45 @@
% This file was created with JabRef 2.10.
% Encoding: UTF8
@Manual{tlv1117,
Title = {TLV1117 Adjustable and Fixed Low-Dropout Voltage Regulator},
Author = {Texas~Instruments},
Month = {12},
Year = {2014},
Owner = {markus},
Timestamp = {2017.11.10},
Url = {http://www.ti.com/lit/ds/symlink/tlv1117.pdf}
}
@Manual{progcable,
Title = {Programming Cables User Guide},
Author = {Lattice~Semiconductor},
Edition = {Version 25.0},
Month = {11},
Year = {2016},
Owner = {markus},
Timestamp = {2017.11.10},
Url = {http://www.latticesemi.com/~/media/LatticeSemi/Documents/UserManuals/MQ/ProgrammingCableUsersGuide.pdf?document_id=143}
}
@Manual{machxo2conf,
Title = {MachXO2 Programming and Configuration Usage Guide},
Author = {Lattice~Semiconductor},
Month = {7},
Year = {2017},
Owner = {markus},
Timestamp = {2017.11.10},
Url = {http://www.latticesemi.com/~/media/LatticeSemi/Documents/ApplicationNotes/MO/MachXO2ProgrammingandConfigurationUsageGuide.pdf?document_id=39085}
}
@Manual{machxo2family,
Title = {MachXO2TM Family Data Sheet},
Author = {Lattice~Semiconductor},
Edition = {Version 3.3},
Month = {3},
Year = {2017},
Owner = {markus},
Timestamp = {2017.11.10},
Url = {http://www.latticesemi.com/~/media/LatticeSemi/Documents/DataSheets/MachXO23/MachXO2FamilyDataSheet.pdf?document_id=38834}
}

BIN
doc/res/schematic.pdf Normal file

Binary file not shown.

View File

@ -0,0 +1,269 @@
% 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, withpage]{acronym}
\usepackage{booktabs}
\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{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}
\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}
In this chapter, all available hardware functions are explained.
\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 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 the IC 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} \\
\ac{io} & 21* \\
LUTs & 1280 \\
Distributed RAM & 10 kbits \\
EBR SRAM & 64 kbits \\
User flash & 64 kbits \\
Hard IPs & 2x i2c, 1x SPI, 1x Timer / Counter, 1x PLL \\ \bottomrule
\end{tabular}
\\ \textit{* Not all \acp{io} may be usable. Refer to chapter \ref{ioheaders}.}
\end{table}
Depending on the version of the board, either speedgrade 4 or 6 are 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 DTR signal from the chip, which is pulled low as soon as the terminal is opened on the PC.
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} 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. This is used to supply 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}.
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}{cll} \toprule
\textbf{Pins} & \textbf{Description} & \textbf{Note} \\ \midrule
\texttt{26} & \acs{jtag} multiplex & See chapter \ref{progopt:multiplex} \\
\texttt{29}, \texttt{30}, \texttt{31}, \texttt{01} & \acs{jtag} & See chapter \ref{progopt:always} \\
\texttt{20}, \texttt{21}, \texttt{23} & \acs{uart} & See chapter \ref{uart} \\
\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 29, 30, 31 and 01 are not available as user \ac{io} in this configuration. All other pins are available as normal user \ac{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 when programming actions are active (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 \ac{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 \ac{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-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}