doc: Add simavr manual

This is an excerpt of the bachelor's thesis "qsimavr: Graphical
Simulation of an AVR Processor and Periphery" by Jakob Gruber. The full
thesis is available at https://github.com/schuay/bachelors_thesis.

doc/manual/Makefile

@@ -0,0 +1,15 @@
+PROJECT = manual
+
+#------------------------------------------------------------------------------
+protocol:
+#------------------------------------------------------------------------------
+	pdflatex $(PROJECT)
+	pdflatex $(PROJECT)
+
+
+#------------------------------------------------------------------------------
+clean:
+#------------------------------------------------------------------------------
+	rm -f *.aux $(PROJECT).bbl $(PROJECT).blg $(PROJECT).log $(PROJECT).dvi \
+		$(PROJECT).toc $(PROJECT).ps $(PROJECT).out
+

doc/manual/acronyms.tex

@@ -0,0 +1,58 @@
+%%
+%% Acronym definitions
+%%
+
+\usepackage{acronym}
+
+\newacro{ADC}{Analog-Digital Converter}
+\newacro{AP}{Address Pointer}
+\newacro{AVR}{Alf and Vegard's Risc processor}
+\newacro{BCD}{Binary Coded Decimal}
+\newacro{CPU}{Central Processing Unit}
+\newacro{CS1}{Chip Select 1}
+\newacro{CS2}{Chip Select 2}
+\newacro{CRC}{Cyclic Redundancy Check}
+\newacro{DDR}{Data Direction Register}
+\newacro{EEPROM}{Electrically Erasable Programmable Read-Only Memory}
+\newacro{ELF}{Executable and Linkable Format}
+\newacro{E}{Enable}
+\newacro{FIFO}{First In, First Out}
+\newacro{GDB}{GNU Debugger}
+\newacro{GLCD}{Graphical Liquid Crystal Display}
+\newacro{GPL}{GNU General Public License}
+\newacro{GUI}{Graphical User Interface}
+\newacro{IDE}{Integrated Development Environment}
+\newacro{ID}{Identifier}
+\newacro{IOCTL}{Input/Output Control}
+\newacro{IO}{Input/Output}
+\newacro{IRQ}{Interrupt Request}
+\newacro{ISR}{Interrupt Service Routine}
+\newacro{JTAG}{Joint Test Action Group}
+\newacro{LCD}{Liquid Crystal Display}
+\newacro{LED}{Light-Emitting Diode}
+\newacro{LSB}{Least Significant Byte}
+\newacro{MCU}{Microcontroller}
+\newacro{MDI}{Multi Document Interface}
+\newacro{MHz}{Megahertz}
+\newacro{MISO}{Master In, Slave Out}
+\newacro{MOSI}{Master Out, Slave In}
+\newacro{MSB}{Most Significant Byte}
+\newacro{NIH}{Not Invented Here}
+\newacro{OpenGL}{Open Graphics Library}
+\newacro{PC}{Program Counter}
+\newacro{RAM}{Random-Access Memory}
+\newacro{RST}{Reset}
+\newacro{RS}{Register Select}
+\newacro{RTC}{Real-Time Clock}
+\newacro{RW}{Read/Write}
+\newacro{SPI}{Serial Peripheral Interface}
+\newacro{SP}{Stack Pointer}
+\newacro{SRAM}{Static Random-Access Memory}
+\newacro{SREG}{Status Register}
+\newacro{TU}{Technical University}
+\newacro{TWI}{Two-Wire Interface}
+\newacro{UART}{Universal Asynchronous Receiver/Transmitter}
+\newacro{VCD}{Value Change Dump}
+\newacro{iff}{if, and only if}
+\newacro{ns}{nanoseconds}
+\newacro{us}[$\mu$s]{microseconds}

doc/manual/introduction.tex

@@ -0,0 +1,7 @@
+\chapter{Introduction}
+
+This manual is an excerpt of the bachelor's thesis ``\emph{qsimavr: Graphical
+Simulation of an AVR Processor and Periphery}'' by Jakob Gruber. The full thesis is available at \url{https://github.com/schuay/bachelors_thesis}.
+
+Chapter \ref{chapter:simavr} provides a brief overview of
+\simavr internals, followed by a setup guide in appendix \ref{chapter:setup}.

doc/manual/manual.tex

@@ -0,0 +1,141 @@
+\documentclass[12pt,a4paper,oneside]{scrreprt}
+
+\usepackage{graphicx}                       % includegraphics-command
+\usepackage{fancyheadings}
+\usepackage[pdfborder={0 0 0}]{hyperref}
+\usepackage[english,germanb]{babel}
+\usepackage[latin1]{inputenc}               % Support direct writing of German Umlauts
+\usepackage{dcolumn}                        % Decimal column formatting
+\usepackage[usenames,dvipsnames]{color}
+\usepackage{listings}
+\usepackage{acronym}
+\usepackage{fancyvrb}                       % Verbatim environment with samepage option
+\usepackage{xspace}                         % Better handling of spaces after custom commands
+\usepackage{chngcntr}                       % Footnote counter settings
+\usepackage[super]{nth}                     % 9th formatting
+\usepackage{booktabs}
+
+\counterwithout{footnote}{chapter}          % Do not reset footnote counter between chapters
+
+
+%%
+%% -------------------------listings configuration----------------------
+%%
+
+\definecolor{Brown}{cmyk}{0,0.81,1,0.60}
+\definecolor{OliveGreen}{cmyk}{0.64,0,0.95,0.40}
+\definecolor{CadetBlue}{cmyk}{0.62,0.57,0.23,0}
+\definecolor{gray}{gray}{0.5}
+
+\lstset{
+    language=C,                             % Code langugage
+    basicstyle=\ttfamily,                   % Code font, Examples:
+                                            % \footnotesize, \ttfamily
+    keywordstyle=\color{OliveGreen},        % Keywords font ('*' = uppercase)
+    commentstyle=\color{gray},              % Comments font
+    captionpos=b,                           % Caption-position = bottom
+    breaklines=true,                        % Automatic line breaking?
+    breakatwhitespace=false,                % Automatic breaks only at
+                                            % whitespace?
+    showspaces=false,                       % Dont make spaces visible
+    showtabs=false,                         % Dont make tabs visible
+    morekeywords={__attribute__},           % Specific keywords
+}
+
+%%
+%% -------------------------Custom commands-----------------------------
+%%
+
+\newcommand{\simavr}{\emph{simavr}\xspace}
+\newcommand{\qsimavr}{\emph{qsimavr}\xspace}
+
+%%
+%% ---------------------------------------------------------------------
+%%
+
+\sloppy
+
+\oddsidemargin 1cm \evensidemargin 1cm \topmargin 0pt
+
+\headsep 50pt \textheight 21.4cm \textwidth 14.1cm
+\setlength{\parskip}{5pt plus2pt minus2pt}
+
+\renewcommand{\floatpagefraction}{0.9}
+\renewcommand{\textfraction}{0.05}
+\renewcommand{\topfraction}{1.0}
+\renewcommand{\bottomfraction}{1.0}
+
+\setcounter{totalnumber}{5}
+\setcounter{bottomnumber}{5}
+\setcounter{topnumber}{5}
+
+\setcounter{tocdepth}{2}
+\addtolength{\abovecaptionskip}{-10pt}
+
+%%
+%% ---------------------------------------------------------------------
+%%
+
+\input{acronyms.tex}
+
+%%
+%% ---------------------------------------------------------------------
+%%
+
+\title{simavr Manual}
+\author{Jakob Gruber \\
+        [email protected]}
+
+%%
+%% ---------------------------------------------------------------------
+%%
+
+\begin{document}
+
+    \pagestyle{empty}
+    \maketitle
+    \cleardoublepage
+
+    \pagestyle{plain}
+    \pagenumbering{roman}
+    \setlength{\parskip}{5pt plus2pt minus2pt}
+
+    \setcounter{page}{1}
+
+    \selectlanguage{english}
+
+    \setlength{\parskip}{1mm}
+    \linespread{0.0}
+
+    \tableofcontents
+    \linespread{1}
+    \clearpage
+    \cleardoublepage
+    \setlength{\parskip}{5pt plus2pt minus2pt}
+
+    \pagestyle{fancy}
+    \renewcommand{\chaptermark}[1]{\markboth{\thechapter\ #1}{}}
+    \renewcommand{\sectionmark}[1]{\markright{\thesection\ #1}{}}
+    \addtolength{\headheight}{2pt}
+
+    \acresetall
+
+    \pagenumbering{arabic}
+    \setcounter{page} {1}
+
+    \cleardoublepage
+    \include{introduction}
+    \cleardoublepage
+    \include{simavr}
+
+    \appendix
+
+    \cleardoublepage
+    \include{setupguide}
+    \cleardoublepage
+
+\end{document}
+
+%%
+%% = eof =====================================================================
+%%

doc/manual/setupguide.tex

@@ -0,0 +1,98 @@
+\chapter{Setup Guide} \label{chapter:setup}
+
+This section provides instructions on how to retrieve, compile and install
+\simavr on the GNU/Linux operating system.
+
+\section{\simavr} \label{section:setup_simavr}
+
+\subsection{Getting the source code}
+
+The official home of \simavr is \url{https://github.com/buserror-uk/simavr}.
+Stable releases are published as git repository tags (direct downloads are
+available at \url{https://github.com/buserror-uk/simavr/tags}). To clone a local
+copy of the repository, run
+
+\begin{verbatim}
+git clone git://github.com/buserror-uk/simavr.git
+\end{verbatim}
+
+\subsection{Software Dependencies}
+
+\emph{elfutils} is the only hard dependency at run-time. The name of this
+package may differ from distro to distro. For example, in Ubuntu the required
+package is called \emph{libelf-dev}.
+
+At compile-time, \simavr additionally requires \emph{avr-libc} to complete its
+built-in AVR core definitions. It is assumed that further standard
+utilities (\emph{git}, \emph{gcc} or \emph{clang}, \emph{make}, etc \ldots) are
+already present.
+
+\simavr has been tested with the following software versions:
+
+\begin{itemize}
+\item Arch Linux x86\_64 and i686
+\item elfutils 0.154
+\item avr-libc 1.8.0
+\item gcc 4.7.1
+\item make 3.82
+\end{itemize}
+
+Furthermore, the board\_usb example depends on libusb\_vhci and vhci\_hcd. For
+further details, see \emph{examples/board\_usb/README}. Note however that these
+are not required for a fully working \simavr build.
+
+\subsection{Compilation and Installation}
+
+\simavr's build system relies on standard makefiles. The simplest compilation
+boils down to the usual
+
+\begin{verbatim}
+make
+make install
+\end{verbatim}
+
+As usual, there are several variables to allow configuration of the build
+procedure. The most important ones are described in the following section:
+
+\begin{itemize}
+\item AVR\_ROOT
+
+The path to the system's \emph{avr-libc} installation.
+
+While the default value
+should be correct for many systems, it may need to be set manually if the
+message 'WARNING \ldots did not compile, check your avr-gcc
+toolchain' appears during the build. For example, if iomxx0\_1.h is located at
+/usr/avr/include/avr/iomxx0\_1.h, AVR\_ROOT must be set to /usr/avr.
+
+\item CFLAGS
+
+The standard compiler flags variable.
+
+It may be useful to modify CFLAGS for easier debugging (in which case
+optimizations should be disabled and debugging information enabled: -O0 -g).
+Additionally adding -DCONFIG\_SIMAVR\_TRACE=1 enables extra verbose output and
+extended execution tracing.
+\end{itemize}
+
+These variables may be set either directly in Makefile.common, or alternatively
+can be passed to the make invocation (make AVR\_ROOT=/usr/avr DESTDIR=/usr
+install).
+
+Installation is managed through the usual
+\begin{verbatim}
+make install
+\end{verbatim}
+
+The DESTDIR variable can be used in association with the PREFIX variable to create a \simavr package. DESTDIR=/dest/dir
+PREFIX=/usr installs to /dest/dir but keeps the package configured to the standard prefix
+(/usr).
+
+For development, we built and installed \simavr with the following procedure:
+
+\begin{verbatim}
+make clean
+make AVR_ROOT=/usr/avr CFLAGS="-O0 -Wall -Wextra -g -fPIC \
+  -std=gnu99 -Wno-sign-compare -Wno-unused-parameter"
+make DESTDIR="/usr" install
+\end{verbatim}