[hwmod.git] / spec / spec.tex

\documentclass[12pt,a4paper,titlepage,oneside]{article}
%\documentclass[12pt,a4paper,titlepage,oneside]{report}

\usepackage{ProtocolHeader}

\begin{document}
\MakeTitleAndTOC

%\chapter %for use with report class
\section
{Einleitung}

Es ist ein einfacher Taschenrechner, der die Grundrechnungsarten Addition, Subtraktion,
Multiplikation und Division beherrscht, auf einem FPGA Board zu realisieren. Dabei soll als Eingabegerät eine PS/2
Tastatur beziehungsweise als Ausgabegerät ein VGA Monitor dienen. Als zusätzliches Feature soll eine
History eingebaut werden, sodass vergangene Berechnungen angezeigt werden
können. Außerdem besteht die Möglichkeit diese History per RS232-Schnittstelle zu
exportieren bzw. importieren.

\section{Requirement Spezifikation}

%TODO: in der Angabe steht nix von einer extrigen Requirement Spezifikation neben der High Level Beschreibung, aber im Template und Auf den Folien ist es als 3. Punkt neben High- und Low Level Spec noch erwähnt.
%
%Die Subsections sind vielleicht ein kleiner Overshoot.


\subsection{Eingabe}

\req{Der Taschenrechner soll eine Eingabe bestehend aus den Ziffern '0'-'9', Leerzeichen ' ', '+', '-', '*' und '/' ausrechnen können}

\req{Der Syntax für so eine Eingabe - eine \textbf{Expression} - sieht folgendermaßen aus:

DIGIT = '0' \textbar '1' \textbar '2' \textbar '3' \textbar '4' \textbar '5' \textbar '6' \textbar '7' \textbar '8' \textbar '9' ;

UNSIGNED = DIGIT \{ DIGIT \} ;

OPERAND = ['-'] UNSIGNED ;

OPERATOR = '+' \textbar '-' \textbar '*' \textbar '/' ;

EXPRESSION = OPERAND \{ OPERATOR OPERAND \} ;
}

\req{Dabei soll Punkt- vor Strichrechnung gelten}

\req{Die Zahlen dürfen im Zahlenbereich eines signed long liegen ($-2^{31}$ bis $2^{31}-1$)}

\req{Die Eingabe darf aus 70 Zeichen bestehen}

\req{Die Eingabe erfolgt über eine PS/2-Tastatur, 'Enter' schließt die Eingabe ab und berechnet das Ergebnis, 'Backspace' löscht das zuletzt eingegebene Zeichen}

\subsection{Ausgabe}

\req{Die Anzeige der Ein- und Ausgaben erfolgt über einen VGA Monitor.}

\req{Es wird pro Zeile eine Eingabe oder Ausgabe angezeigt. Die aktuelle Eingabezeile befindet sich zuoberst, darunter das Ergebnis der vorigen Rechnung, darunter die Eingabe der vorigen Rechnung und so weiter}

\req{Auf die in zuvor angegebene Methode sollen zusätzlich zur aktuellen Eingabezeile die letzten 14 Ein- und Ausgaben dargestellt werden}

\subsection{History}

\req{Die letzten 50 Ein- und Ausgaben korrekter Eingaben werden als History im Speicher gehalten}

\req{Die History soll über RS232, auf Anfrage vom PC, oder bei Betätigen eines Buttons am Development Board, zum PC gesendet werden}


\section{High-Level Design Description}

\begin{figure}[!ht]
\includegraphics[width=\textwidth]{Architektur.png}
\centering
\caption{Die Architektur des Taschenrechners}
\label{fig:arch}
\end{figure}

In Abbildung \ref{fig:arch} ist der Aufbau des Taschenrechners zu sehen. Der Taschenrechner besteht aus folgenden Modulen:

%\subsection{Module}

\begin{itemize}
\item \textbf{VGA} - Zeichenweises Ansprechen des Monitors
\item \textbf{PS/2} - Empfangen von Keyboard-Eingaben als Scancodes
\item \textbf{RS232} - Senden und Empfangen von Nachrichten vom/zum PC über die serielle Schnittstelle % TODO. baudrate? kodierung? (8N1?)
\item \textbf{Scanner} - Empfängt die Scan-Codes vom PS/2 Modul und leitet nur für die Eingabezeile erlaubte Zeichen dekodiert in das CP850 Format an die History weiter, bei einem empfangenen Enter wird der Beginn der Berechnung an das Parser Modul signalisiert
\item \textbf{History} - Verwaltung des dahinterliegenden Buffers von vergangenen Berechnungen und der aktuellen Eingabezeile, bei Aktualisierung der aktuellen Eingabezeile und bei Empfang eines Ergebnisses vom Parser Modul signalisiert es das an das Display Modul
\item \textbf{Parser} - Wertet die Eingabezeile der History aus und liefert als Antwort entweder einen Fehler zurück oder gibt die einzelnen Berechnungen von je zwei Zahlen an die ALU weiter, die vom History Modul ausgelesenen zusammenhängenden Dezimalstellen werden mit dem Bin/Dez-Converter Modul in Binärzahlen umgerechnet, das Berechnungs-Endergebnis wird wieder in mit dem Converter Modul in einzelne Charakter umgerechnet und in der History gespeichert
\item \textbf{Bin/Dez-Converter} - Konvertiert 10 CP850-codierte Dezimalziffern mit Vorzeichen in eine Binärzahl und umgekehrt %TODO oder in Parser integrieren? Oder gibt's eine Library-Funktion dafür?
\item \textbf{ALU} - Führt die tatsächlichen Berechnungen von Addition, Subtraktion, Multiplikation und Division durch
\item \textbf{Display} - Liest einzelne Zeichen aus der History aus und leitet diese an das VGA Modul weiter, um sie in der entsprechenden Zeile anzeigen zu lassen
\item \textbf{PC-Kommunikation} - Auf eine vom PC eintreffende Bufferübermittlungsanforderung oder ein Drücken des entsprechenden Board-Buttons, liest es Zeichen für Zeichen aus dem History Modul aus und leitet es an das RS232 Modul weiter
\end{itemize}

%\subsection{Interfaces}

\subsection{Externe Interfaces}

\subsubsection{Physikalische Interfaces}

%TODO die pins sind wahrscheilich gefragt
%wie ist das mit dem clock? externe ungenaue clock + interne pll oder wie?

Interface zum key pad

Interfaces zu VGA, PS/2, RS232

Reset und Clock!

Active Low oder Active High

das ist mir noch nicht ganz klar was die da wollen. was meinen die z.b. mit ``interfaces
to VGA'' unter ``physical interfaces'' (seite 10 in der exercise.pdf)

``physikalisch'' im sinne der VHDL entity? oder doch den physischen stecker?
Ersteres wuerde ich unter Logisches Interface verstehen.

\subsubsection{Logische Interfaces der Module}
\begin{landscape}

\paragraph{VGA}
\THEAD
vga\_clk & in & 1 & std\_logic & PLL & VGA-Clock \ZE
vga\_res\_n & in & 1 & std\_logic & PLL & VGA-Reset \ZE

vsync\_n & out & 1 & std\_logic & Bildschirm & Vertikale Synchronisation\ZE
hsync\_n & out & 1 & std\_logic & Bildschirm & Horizontale Synchronisation\ZE

r & out & 3 & std\_logic\_vector & Bildschirm & Ausgabe der Farbe Rot \ZE
g & out & 3 & std\_logic\_vector & Bildschirm & Ausgabe der Farbe Gr\"un \ZE
b & out & 2 & std\_logic\_vector & Bildschirm & Ausgabe der Farbe Blau \ZE

command & in & 8 & std\_logic\_vector & Display & Kommando an das VGA Modul \ZE
command\_data & in & 32 & std\_logic\_vector & Display & Daten f\"ur das Kommando \ZE
free & in & 1 & std\_logic & Display & Signalisiert Bereitschaft \ZE
\TEND


\paragraph{PS/2}
\THEAD
new\_data & out & 1 & std\_logic\_vector & Scanner & Signalisiert neuen Scancode \ZE
data & out & 8 & std\_logic\_vector & Scanner & Scancode laut Codepage 850 \ZE

ps2\_clk & inout & 1 & std\_logic & Tastatur & Clockleitung zum Keyboard \ZE
ps2\_data & inout & 1 & std\_logic & Tastatur & Datenleitung zum Keyboard \ZE
\TEND


\paragraph{RS232}
%Senden und Empfangen von Nachrichten vom/zum PC über die serielle Schnittstelle
\THEAD
rxd & in & 1 & std\_logic & PC & Sendeleitung der seriellen \"Ubertragung \ZE
txd & out & 1 & std\_logic & PC & Empfangsleitung der seriellen \"Ubertragung \ZE

rx\_data & out & 8 & std\_logic\_vector & PC-Kommunikation & Datenfeld f\"ur das Empfangen \ZE
rx\_new & out & 1 & std\_logic & PC-Kommunikation & Signalisiert ein neu empfangendes Byte \ZE

tx\_data & out & 8 & std\_logic\_vector & PC-Kommunikation & Datenfeld f\"ur das \"Ubertragen \ZE
tx\_new & out & 1 & std\_logic & PC-Kommunikation & Signalisiert dass das anliegende Byte gesendet werden soll \ZE
\TEND

\paragraph{Scanner}
%Empfängt die Scan-Codes vom PS/2 Modul und leitet nur für die Eingabezeile erlaubte Zeichen dekodiert in das CP850 Format an die History weiter, bei einem empfangenen Enter wird der Beginn der Berechnung an das Parser Modul signalisiert
\THEAD
new\_data & in & 1 & std\_logic\_vector & PS/2 & Signalisiert neuen Scancode \ZE
data & in & 8 & std\_logic\_vector & PS/2 & Scancode laut Codepage 850 \ZE

char & out & 8 & character & History & Zeichen das vom History Modul \"ubernommen werden soll \ZE
take & out & 1 & std\_logic & History & Signalisiert Datenfeld char \ZE
backspace & out & 1 & std\_logic & History & Signalisiert Backspace (letztes Zeichen im Buffer soll gel\"oscht werden) \ZE

do\_it & out & 1 & std\_logic & Parser & Auswertung beginnen (ENTER) \ZE
finished & in & 1 & std\_logic & Parser & Auswertung fertig \ZE
\TEND


\paragraph{History}
%Verwaltung des dahinterliegenden Buffers von vergangenen Berechnungen und der aktuellen
%Eingabezeile, bei Aktualisierung der aktuellen Eingabezeile und bei Empfang eines Ergebnisses vom
%Parser Modul signalisiert es das an das Display Modul
\THEAD
pc\_zeile & in & 7 & std\_logic\_vector & PC-Kommunikation & Zeilenadressierung (50 * 2 Zeilen = 100)\ZE
pc\_spalte & in & 7 & std\_logic\_vector & PC-Kommunikation & Spaltenadressierung (71 Zeichen inklusive \textbackslash 0) \ZE
pc\_get & in & 1 & std\_logic & PC-Kommunikation & Signalisiert Speicheranforderung \ZE
pc\_done & out & 1 & std\_logic & PC-Kommunikation & Signalisiert dass Daten anliegen \ZE
pc\_char & out & 8 & character & PC-Kommunikation & enth\"alt angeforderne Daten \ZE

s\_char & in & 8 & character & Scanner & Zeichen das vom Scanner Modul \"ubernommen werden soll \ZE
s\_take & in & 1 & std\_logic & Scanner & Signalisiert Datenfeld char \ZE
s\_backspace & in & 1 & std\_logic & Scanner & Signalisiert Backspace (letztes Zeichen im Buffer soll gel\"oscht werden) \ZE

d\_new\_eingabe & out & 1 & std\_logic & Display & Fordert Display auf die Eingabe auszulesen \ZE
d\_new\_result & out & 1 & std\_logic & Display & Fordert Display auf das Ergebnis auszulesen \ZE
d\_zeile & in & 5 & std\_logic\_vector & Display & Zeilenadressierung ($2 * 15$ Zeilen $=30$) \ZE
d\_spalte & in & 7 & std\_logic\_vector & Display & Spaltenadressierung (71 Ziechen inklusive \textbackslash 0) \ZE
d\_get & in & 1 & std\_logic & Display & Signalisiert Speicheranforderung \ZE
d\_done & out & 1 & std\_logic & Display & Signalisiert dass Daten anliegen \ZE
d\_char & out & 8 & character & Display & enth\"alt angeforderne Daten \ZE

p\_rw & in & 1 & std\_logic & Parser & 0 = read (Expression), 1 = write (Ergebnis) \ZE
p\_spalte & in & 7 & std\_logic\_vector & Parser & Spaltenadressierung (71 Ziechen inklusive \textbackslash 0) \ZE
p\_rget & in & 1 & std\_logic & Parser & Signalisiert Leseanforderung \ZE
p\_rdone & out & 1 & std\_logic & Parser & Signalisiert dass Daten anliegen \ZE
p\_read & in & 8 & character & Parser & enth\"alt angeforderne Daten \ZE

p\_wdo & in & 1 & std\_logic & Parser & Signalisiert Schreibanforderung \ZE
p\_wdone & out & 1 & std\_logic & Parser & Signalisiert dass Daten anliegen \ZE
p\_write & out & 8 & character & Parser & enth\"alt zu schreibende Daten \ZE

p\_finished & in & 1 & std\_logic & Parser & Auswertung fertig \ZE
\TEND

\paragraph{Parser}
%Wertet die Eingabezeile der History aus und liefert als Antwort entweder einen Fehler zurück oder gibt die einzelnen Berechnungen von je zwei Zahlen an die ALU weiter, die vom History Modul ausgelesenen zusammenhängenden Dezimalstellen werden mit dem Bin/Dez-Converter Modul in Binärzahlen umgerechnet, das Berechnungs-Endergebnis wird wieder in mit dem Converter Modul in einzelne Charakter umgerechnet und in der History gespeichert
\THEAD
h\_rw & in & 1 & std\_logic & History & 0 = read (Expression), 1 = write (Ergebnis) \ZE
h\_spalte & in & 7 & std\_logic\_vector & History & Spaltenadressierung (71 Ziechen inklusive \textbackslash 0) \ZE
h\_rget & in & 1 & std\_logic & History & Signalisiert Leseanforderung \ZE
h\_rdone & out & 1 & std\_logic & History & Signalisiert dass Daten anliegen \ZE
h\_read & in & 8 & character & History & enth\"alt angeforderne Daten \ZE

h\_wdo & in & 1 & std\_logic & History & Signalisiert Schreibanforderung \ZE
h\_wdone & out & 1 & std\_logic & History & Signalisiert dass Daten anliegen \ZE
h\_write & out & 8 & character & History & enth\"alt zu schreibende Daten \ZE

h\_finished & in & 1 & std\_logic & History & Auswertung fertig \ZE

opcode & out & 3 & enum OPS & ALU & die auszuf\"uhrende Art der Berechnung \ZE
op1 & out & 32 & SIGNED(32-1 downto 0) & ALU & erste Operand \ZE
op2 & inout & 32 & SIGNED(32-1 downto 0) & ALU & zweite Operand und gleichzeitig der Zieloperand \ZE
do\_calc & out & 1 & std\_logic & ALU & Signalisert Berechnungstart \ZE
calc\_done & in & 1 & std\_logic & ALU & Berechnung fertig \ZE

do\_it & in & 1 & std\_logic & Scanner & Auswertung beginnen (ENTER) \ZE
finished & out & 1 & std\_logic & Scanner & Auswertung fertig \ZE
\TEND


\paragraph{ALU}
%Führt die tatsächlichen Berechnungen von Addition, Subtraktion, Multiplikation und Division durch
\THEAD
opcode & in & 3 & enum OPS & Parser & die auszuf\"uhrende Art der Berechnung \ZE
op1 & in & 32 & SIGNED(32-1 downto 0) & Parser & erste Operand \ZE
op2 & inout & 32 & SIGNED(32-1 downto 0) & Parser & zweite Operand und gleichzeitig der Zieloperand \ZE
do\_calc & in & 1 & std\_logic & Parser & Signalisert Berechnungstart \ZE
calc\_done & out & 1 & std\_logic & Parser & Berechnung fertig \ZE
\TEND


\paragraph{Display}
TODO
%Liest einzelne Zeichen aus der History aus und leitet diese an das VGA Modul weiter, um sie in der entsprechenden Zeile anzeigen zu lassen

allgemein: sys\_clk (in), sys\_res\_n (in)

zum modul history: 1 bit new\_eingabe (in), 1 bit new\_result (in), 5 bit zeile (2*14+1) (out), 7 bit spalte (71 zeichen - 0 am ende notwendig?) (out), 1 get bit (out), 1 done bit (in), 8 daten bits (in)

zum modul vga: 8 bit command (out), 32 bit command\_data (out), 1 bit free (in)

\paragraph{PC-Kommunikation}

TODO

%Auf eine vom PC eintreffende Bufferübermittlungsanforderung oder ein Drücken des entsprechenden Board-Buttons, liest es Zeichen für Zeichen aus dem History Modul aus und leitet es an das RS232 Modul weiter

allgemein: sys\_clk (in), sys\_res\_n (in)

ein Pin zum externen Button (in)

zum modul rs232: 8 Empfangsbits (in), 1 Received Flag (in), 8 Sendebits (out), 1 Sendflag (out)

zum modul history: 5 bit zeile (2*14+1) (out), 7 bit spalte (71 zeichen - 0 am ende notwendig?) (out), 1 get bit (out), 1 done bit (in), 8 daten bits (in)
\end{landscape}

\subsubsection{Verhalten der Interfaces}

welche tasten als input erlauben (haben numblock und normale ziffern unterschiedliche scancodes?)?

wie werden ueberlaeufe behandelt?

fehlerhafte eingaben?

wie schaut die ausgabe aus?

was ausgaben bei fehler?

wie kann download oder upload einer history gestartet werden?

wie kann auf die history zugegriffen werden?

soll in der eingabe auch mit pfeiltasten (links,rechts) gescrolled werden koennen?


\subsection{Testfälle}

alle requirements muessen von testfaellen abgedeckt werden!

%29 zeilen am bildschirm


\section{Detailed Design Description}

alle Module hier genauer beschreiben

%TODO
wie wollen wir das design implementieren?

event sequence diagrams! UML?

wie schauen interne strukturen aus? (speicher, logische bloecke, parallele prozesse, state machines)

\subsection{VGA}

\subsection{PS/2}

\subsection{RS232}
%test, TODO
\begin{figure}[!ht]
\includegraphics[width=0.9\textwidth]{sm/rs232-rs.pdf}
\centering
\caption{Statemachine zum Empfangen auf der RS232 Schnittstelle (8N1)}
\label{fig:rs232-rs}
\end{figure}

\subsection{Scanner}
\begin{figure}[!ht]
\includegraphics[width=0.9\textwidth]{sm/scanner.pdf}
\centering
\caption{Statemachine zum Scannen des Inputs der PS/2 Schnittstelle}
\label{fig:scanner}
\end{figure}

\begin{itemize}
\item \textbf{idle}: Setz alle Steuersignale \emph{backspace}, \emph{take} und \emph{do\_it} low.
\item \textbf{read}: Bei steigender Flanke auf \emph{new\_data} wird das anliegende Byte des
PS/2-Modules \"ubernommen. Je nach Wert wird in den n\"achsten Zustand gewechselt.
\item \textbf{enter}: Wurde die Entertaste gedr\"uckt wird der Parser getriggert (\emph{do\_it} ist
einen Takt lang high). Der Scanner befindet sich so lange in diesem Zustand bis der Parser das
Ergebnis berechnet hat.
\item \textbf{l\"oschen}: Teilt dem History Modul mit das letzte Zeichen im Buffer zu l\"oschen
(\emph{backspace} ist einen Takt lang high).
\item \textbf{\"ubernehmen}: Wenn ein g\"ultiges Zeichen laut Requirements eingegeben wurde, wird
jenes Zeichen an \emph{char} angelegt und \emph{take} wird einen Takt lang high gesetzt. Das History
Modul wird dadurch getriggert das anliegende Zeichen in den Buffer zu \"ubernehmen.
\end{itemize}


\subsection{History}

\subsection{Parser}
\begin{figure}[!ht]
\includegraphics[width=0.9\textwidth]{sm/parser.pdf}
\centering
\caption{Statemachine zum Parsen der aktuellen Expression}
\label{fig:parser}
\end{figure}

\begin{lstlisting}
procedure exec() {
        z := z*s;
        switch(opp) {
                case NOP: 
                        if(aktop != '\0')
                                c1();
                        break;
                case '-':
                        z := z * (-1);
                case '+':
                        c1();
                        break;

                case '/':
                case '*':
                  if(aktop in ['+','-','\0']) {
                          alu(opp, z, punkt);
                          do_calc = 1;
                          while(calc_done == 0);

                          alu(ADD, punkt, strich);
                          punkt = 1;
                  }
                  else if (aktop in ['*','/']) {
                          alu(opp, z, punkt);
                  }
                  break;
        }
        do_calc = 1;
        opp = aktop;
}

procedure c1() {
        if(aktop in ['+','-','\0']) {
                alu(ADD, z, strich);
        }
        else if (aktop in ['*','/']) {
                alu(MUL, z, punkt);
        }
}
\end{lstlisting}

\begin{itemize}
\item \textbf{idle}: Das Modul ist unt\"atig und wartet auf eine steigende Flanke von \emph{do\_it}.

\item \textbf{read char}: Lokale Variablen werden zur\"uckgesetzt und das n\"achste Zeichen wird vom
History Modul angefordert.

\item \textbf{sign}: Ggf. wird das Vorzeichen auf '-' gesetzt.

\item \textbf{calc}: Zeichen f\"ur Zeichen wird eingelesen und die Zahl wird daraus berechnet.

\item \textbf{ALU}: Punkt- und Strichrechnungen m\"ussen getrennt behandelt werden, daher ergibt
sich dieses Konstrukt im Codebeispiel.

\item \textbf{null}: Sonderbehandlung ist n\"otig wenn die Expression mit '\textbackslash 0'
abgeschlossen wird.

\item \textbf{done}: In diesem Zustand wird das Ergebnis das sich je nach \emph{opp} in
\emph{strich} oder \emph{punkt}  befindet als String in den Ergebnisbuffer des History Modules
geschrieben und danach wird \emph{finished} f\"ur einen Zyklus auf high gesetzt.

\item \textbf{error}: Zwecks \"Ubersichtlichkeit wurden die Transitionen zu diesem Zustand
vernachl\"assigt. Dieser Zustand wird erreicht sobald ein Grammatikfehler oder ein Fehler der ALU
auftritt. Es wird der String ``Error'' in den Ergebnisbuffer geschrieben und
\emph{finished} wird f\"ur einen Zyklus auf high gesetzt.
\end{itemize}


\subsection{Bin/Dez-Converter}

\subsection{ALU}
opcodes: NOP, ADD, MUL, DIV, DONE (als enum)

\subsection{Display}

\subsection{PC-Kommunikation}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%LISTINGS
%\newpage
%\appendix
%\section{Listings}
%howto include src files
%\subsection{einfache Variante -- generierter Sourcecode}
%\label{att:einfachsrc}
%\lstinputlisting{../einfach/einfach.src}
%\lstinputlisting[firstnumber=24, firstline=24, lastline=34]{bla.src} %firstnumber shouldn't be necessary, but there is probably a bug

\end{document}