summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/avremu/avremu.tex
blob: 3fe7b693e80d22c852588c6f46c3336a133ae6fb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
\documentclass{article}
\usepackage{avremu}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{filecontents}
\usepackage{tcolorbox}
\usepackage{ydoc}

\def\fileversion{v0.1}
\def\filedate{2014/10/09}

\makeatletter
\def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}}
\def\cmd@to@cs#1#2{\char\number`#2\relax}
\DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}}
\makeatother

\begin{filecontents*}{hello-world.c}
#include <avr/io.h>

int
main(void)
{
  char *str = "Hello World!";
  char *p = str;
  while (*p) {
    UDR = *p++;
  }
  asm  volatile ("break;");
}
\end{filecontents*}

\title{The \texttt{avremu} Package}
\author{Christian Dietrich\\
\url{stettberger@dokucode.de}\\
\url{https://gitlab.brokenpipe.de/stettberger/avremu}}

\begin{document}

\maketitle

\begin{tcolorbox}
  \lstinputlisting[language=C]{hello-world.c}
  \tcblower
  \begin{lstlisting}[language=TeX]
\avrloadc{hello-world.c}
\avrrun
UDR='\avrUDR' in \avrinstrcount\ instructions
\end{lstlisting}
\end{tcolorbox}
\begin{tcolorbox}
\avrloadc{hello-world.c}\avrrun
UDR='\avrUDR' in \avrinstrcount\ instructions
\end{tcolorbox}


\LaTeX\ is known as a typesetting system. But the underlying \TeX\ system is a powerful macro
processor. In fact, TeX is a Turing-complete programming language. \TeX\ can compute anything that
is computable. Computeability is a concept from theoretical computer science. After visiting a
theoretical computer-science course, you will know that there are things that cannot be solved by a
machine. Never. Look out for the halting problem. 

This package does contain an \emph{CPU emulator} for the 8-bit microcontroller platform Atmel AVR, more
precisely it implements the instruction-set architecture of the \texttt{ATmega8}.

\begin{tcolorbox}
\begin{lstlisting}[language=TeX]
\avrloadc{mandelbrot.c}
\avrrun

\avrdrawppm{mandelbrot.ppm}
\immediate\write18{convert mandelbrot.ppm mandelbrot.png}
  
\includegraphics[width=\linewidth]{mandelbrot.png}
\end{lstlisting}
  \tcblower
  This picture (250x250) took 44 hours to render. The source code can be found in the test-suite
  directory under mandelbrot.c.\\

  \includegraphics[width=\linewidth]{imgs/mandelbrot-250x250}
\end{tcolorbox}

\section{Provided Commands}

\DescribeMacro{\avrloadihex}{\meta{filename}}
Load an Intel HEX formatted image of the flash into the code memory of the AVR
emulator. Additionally the state of the AVR emulator is set back to zero.

\DescribeMacro{\avrloadc}[\meta{compiler options}]{\meta{filename}}
Requires \verb|--shell-escape|. Compiles C source code file with \verb|avr-gcc| and the given
compiler options. The default compiler option set is \verb|-mmcu=atmega8 -Os|. The resulting
\texttt{.elf} file is transformed to an Intel HEX file and loaded into the code memory of the
emulator.

\DescribeMacro{\avrrun}
Run the emulator until a \textbf{break} instruction occurs.

\DescribeMacro{\avrstep}[\meta{steps}=1]
Run the emulator for N instructions. The default is a single step. The stepping does automatically
end, if a \textbf{break} instruction is executed.

\DescribeMacro{\avrinstrcount}
Expands to the number of executed instructions.

\DescribeMacro{\avrsinglestep}
Starts an interactive single-stepping mode, which was mainly used for implementing the emulator.

\DescribeMacro{\usravremulibrary}{\meta{list of libraryies}}

\subsection{Access to the Serial Console}
If the program write to the \verb|UDR| IO register, the emulator catched those characters in an
internal buffer.

\DescribeMacro{\avrUDR}
Expands to the internal UDR buffer.

\DescribeMacro{\avrUDRclear}
Clears the internal UDR buffer.

\subsection{Draw Library}
\DescribeMacro{\useavremulibrary}{avr.draw}

See source/test-suite/mandelbrot.c for more details.

\section{Implementation Details}
Read the source.
\end{document}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: