Début de la rédaction du rapport sur le projet.

2 files changed, 97 insertions, 71 deletions

diff --git a/doc/rapport_cpu.pdf b/doc/rapport_cpu.pdf
new file mode 100644
index 0000000..e18eec7
--- /dev/null
+++ b/doc/rapport_cpu.pdf
diff --git a/doc/rapport_cpu.tex b/doc/rapport_cpu.tex
index d7901db..67aa4c1 100644
--- a/doc/rapport_cpu.tex
+++ b/doc/rapport_cpu.tex
@@ -12,109 +12,135 @@
 
 
 
-\title{Programmation d'un simulateur de net-lists \\ \normalsize{\textsc{Projet de Système digital}}}
-\author{Jonathan Laurent}
+\title{Conception and realization of the VIVACE architecture
+             \\ \normalsize{\textsc{Projet de Système digital}}}
+\author{A.Auvolat, E.Enguehard, J.Laurent}
 \maketitle
 
 
-Le programme \prog{netsim} permet de simuler un circuit digital synchrone représenté par une net-list. Il propose notamment les fonctionnalités suivantes :
+The VIVACE\footnote{Virtually Infaillible VIVACE Automated Computing Environment} architecture is
+a minimalistic 16 bits RISC microprocessor architecture, largely inspired by the MIPS
+microprocessor.
+
+
+The principal characteristics of the architecture are :
 
 \begin{itemize}
-\item Un \textit{mode interactif} suffisament riche pour permettre un déboguage efficace des net-lists
-\item Le maintien d'un \textit{historique} des états de la machine permettant d'annuler certaines actions
-\item La \textit{vérification} de la cohérence des net-lists passées en entrée
+\item \textit{8 general-purpose registers}, which can hold 16 bits integers : \prog{Z, A, B, C, D, E, F, G}
+\item \textit{16 bit memory addressing}, enabling the CPU to use up to $64kb$ of memory.
 \end{itemize}
 
-\section{Guide d'utilisation}
-\subsection{Commande et options}
-
-Le programme se lance avec la commande 
+In order to implement and run the architecture, the following programs have been written :
 
-\begin{center}\prog{./netsim NETLIST\underscore{}FILE [--rom ROM\underscore{}FILE] [-f INPUT\underscore{}FILE] }\end{center}
+\begin{itemize}
+\item \textit{Netlist  simulator} and \textit{netlist optimizer}
+\item An \textit{OCaml library} for generating netlists from Caml code
+\item The code for the \textit{CPU implementation} (written in Caml)
+\item A \textit{monitor} which is used to interact dynamically with the netlist simulator
+\item An \textit{assembler} which can be used to produce the ROM files run by the CPU.
+\end{itemize}
 
-où \prog{NETLIST\underscore{}FILE} désigne un fichier contenant le circuit à simuler, \prog{ROM\underscore{}FILE} contient le contenu des mémoires \textsc{rom}s et \prog{INPUT\underscore{}FILE} contient une suite de directives à executer avant le démarrage du \textit{mode interactif}.
+\section{How to run the VIVACE cpu}
+\subsection{Preparation}
 
-\medskip
+All the tools described in the introduction must first be compiled :
 
-Dans la suite de ce document :
-\begin{itemize}
-\item \prog{val} désigne une valeur, c'est à dire l'état d'une nappe de fils où les bits sont présentés dans l'ordre \emph{décroissant}
-\item \prog{addr} représente une valeur codant pour une adresse
-\item \prog{id} désigne l'identifiant d'une variable présente dans le fichier net-list courant
-\item \prog{cell} désigne une variable ou un emplacement \textsc{ram} de la forme \prog{id : addr} où \prog{addr} est une valeur codant pour une adresse
+\begin{verbatim}
+    $ cd csim; make; cd .. 
+    $ cd sched; make; cd .. 
+    $ cd monitor; make; cd ..
+    $ cd asm; make; cd ..
+\end{verbatim}
 
-\end{itemize}
+To run the VIVACE CPU, type the following :
 
-\subsection{Format des fichiers ROM}
+\begin{verbatim}
+    $ cd cpu; make
+\end{verbatim}
 
-Un fichier \textsc{rom} est composé d'une suite de blocs. Un bloc est composé d'un entête de la forme suivante
-\begin{center}\prog{ROM id ADDRSIZE n$_1$ WORDSIZE n$_2$ }\end{center}
-où les deux arguments numériques sont fournis en écriture décimale. Le contenu de la mémoire correspondant à un entête est décrit par une suite de valeurs ordonnées dans le sens des adresses croissantes. Il est possible de sauter directement à une adresse spécifiée avec la directive 
-\begin{center}\prog{ADDR addr :}\end{center}
-Un exemple est fourni dans le dossier \prog{samples} du programme.
+\subsection{Monitor commands}
 
-\subsection{Le language de scripts d'interaction}
+You are now running the VIVACE CPU. The monitor accepts a few commands to control the simulation.
+First, you must configure the monitor to communicate with the CPU :
 
-\medskip
+\begin{verbatim}
+    t 0
+    s 1 19 18
+    d7 20 21 22 23 24 25 26 27
+\end{verbatim}
 
-Après affichage de l'invite de commande \prog{>}, l'utilisateur peut saisir plusieurs directives, séparées par des points ou des sauts de lignes. La directive la plus simple consiste à entrer une séquence de valeurs \prog{val} séparées par des espaces, et correspondant à chaque entrée du circuit, dans l'ordre de leur déclaration au sein du fichier net-list. Le logiciel exécute alors un cycle machine à partir de ces entrées et affiche les nouvelles valeurs des sorties. Il est également possible de saisir une liste d'affectations suivant l'exemple suivant :
-\begin{center}
-\prog{a = 0, b = 0110, c = 10}
-\end{center}
-Les entrées su circuit qui n'auront pas été mentionnées dans la liste garderont leur valeur précédente. Il est également possible d'utiliser une des directives suivantes :
+The first command sets up the tick input (a tick is sent once every second on this input by the monitor). The
+second command sets up the serial input/output. The third command sets up the 7-segment display (8 digits displayed).
+Now, use the following commands to control the simulation :
 
-\medskip
-\begin{center}
 \begin{itemize}
-   \item \prog{\%inputs id$_1$ ... id$_n$} spécifie une nouvelle liste ordonnée des entrées du circuit
-   \item \prog{\%outputs cell$_1$ ... cell$_n$} spécifie la liste des sorties du circuit
-   \item \prog{\%show cell$_1$ ... cell$_n$} affiche la valeur des variables et emplacements \textsc{ram} indiqués. En l'absence d'arguments, la valeur des sorties est affichée
-   \item \prog{\%run n}  exécute $n$ cycles machine
-   \item \prog{\%echo off} désactive l'affichage  automatique des sorties après exécution d'un cycle. Pour réactiver cette fonctionnalité, remplacer \prog{off} par \prog{on}
-   \item \prog{\%echo on} active l'affichage des sorties
-   \item \prog{\%undo n}  annule les $n$ dernières commandes ayant eu pour effet d'exécuter des cycles machine. Si l'argument n'est pas spécifié, $n=1$
-   \item \prog{\%redo n} annule un appel anterieur de \prog{\%undo n}, si aucune opération d'écriture n'a été excutée d'ici là
-   \item \prog{\%history n} redéfinit la valeur de la capacité de l'historique permettant d'effectuer des \prog{undo}
-   
+    \item \prog{a} run the simulation at full speed
+    \item \prog{m} run the simulation step by step (enter an empty command to run a step)
+    \item \prog{f <freq>} run the simulation at fixed frequency (frequency is dynamically ajusted so
+            this is not very accurate)
+    \item \prog{q} exit simulation
 \end{itemize}
-\end{center}
 
-Des exemples sont disponnibles dans le dossier \prog{samples} du programme.
-\section{Carcatéristiques techniques}
+The CPU recieves commands on the serial input. To send a command to the CPU, use the following syntax :
 
-Une exécution du programme se déroule schématiquement de la manière suivante :
+\begin{verbatim}
+    :<cpu_command>
+\end{verbatim}
 
-\paragraph{Au chargement d'un fichier net-list :}
-\begin{itemize}
-\item Les équations sont triées dans l'ordre topologique et tout cycle d'exécution est signalé
-\item Une vérification de la cohérence des types est effectuée
-\item La liste d'équations est précompilée (voire suite)
-\end{itemize}
+For instance:
 
-\paragraph{A chaque cycle :}
-\begin{itemize}
-\item Les valeurs des mémoires \textsc{ram} sont mises à jour en fonction de l'état de la machine à la fin du cycle \emph{précédent}. Le membre gauche d'une équation de type \textsc{ram} ne dépend ainsi dans l'ordre topologique que du paramètre de l'adresse de lecture.
-\item Chaque équation modifie l'état courant sur la base de l'état de la machine à la fin du cycle précédent (calcul des valeurs des registres) et de l'état obtenu après exécution des équations antérieures (par rapport à l'ordre topologique)
-\end{itemize}
+\begin{verbatim}
+    :Y2014
+\end{verbatim}
+
+These commands are essentially used to set one of the six variables \prog{YMDhms} ; the syntax is similar to the
+example command given above. An empty CPU command tells the CPU to just tell us what time and what day it is.
+
+
+\section{Program details}
+\subsection{Generating netlists from Caml code}
+
+We have developped a library that enables us to easily generate netlists from Caml code. The Caml code we write
+has the same abstraction level that MiniJazz has, but it is more comfortable to write circuits like this than
+with MiniJazz code.
 
-\medskip
+The library functions are defined in \prog{cpu/netlist\_gen.mli}. Basically, we have created functions that build
+the graph of logical operations. The abstract type \prog{t} is actually a closure to a function that adds the
+required equation to a netlist program being built, therefore the generation of a netlist consists in two steps :
+the generation of a closure graph that describes the graph of logical operations, and the execution of these
+closures on a program which, at the beginning, has only the circuit inputs. The equations are progressively
+added to the program when the closures are called.
 
-Pour plus de détails, le lecteur est invité à consulter le fichier \emph{netlist\underscore{}simulator.ml}.
+The VIVACE CPU has been entirely realized using this library.
 
-\subsection{Optimisations}
-Afin de rendre le programme raisonnablement efficace, deux optimisations ont été principalement mises en oeuvre :
+\subsection{The VIVACE CPU}
+
+\subsubsection{Control structure}
+
+The CPU is able to execute instructions that need several cycles to run. The two first cycles of an instruction's
+execution are used to load that instruction (16 bits have to be read, ie two bytes). Most instructions finish
+their execution on the second cycle, but some executions need more cycles to run :
 
 \begin{itemize}
-\item Chaque variable se voit affecter un identifiant numérique et l'état de toutes les variables de la machine est stockée dans un tableau. Cependant, le type \prog{state} exporté par \prog{Netlist\underscore{}simulator} est persistent (le tableau est recopié à la fin de toutes les fonctions exportées par la signature du module), ce qui permet de gérer plutôt simplement un historique.
-\item La liste des équations est précompilée en une liste de fonctions du type \prog{state -> state -> state} de manière à ce que la structure de ses éléments ne soit pas réexplorée à chaque cycle. Pour plus d'explications, consulter \emph{netlist\underscore{}simulator.ml}.
+    \item Load and store instructions need one or two extra cycles
+    \item The multiplication operation needs as many cycles as the position
+        of the most-significant non-null bit in the second operand.
+    \item The division always runs on 16 cycles.
 \end{itemize}
 
-\medskip
+The execution of instructions on several cycles is implemented using a ``control bit'' that cycles through
+several steps : load instruction, various steps of instruction execution.
+
+The instruction decoding mechanism is in \prog{cpu.ml} which is well-commented.
+
+\subsubsection{ROM, RAM and MMIO
+
+\subsubsection{The ALU}
 
-Ces deux améliorations représentent un gain de temps d'un facteur 12 environ environ. A titre indicatif, la simulation de $84000$ cycles du circuit à $300$ variables \prog{clockHMS} prend $3s$.
+\subsection{The assembler}
 
-\subsection{Améliorations possibles}
+\subsection{The simulator and the monitor}
 
-Le système actuel génère des erreurs très imprécises et ne vérifie pas la sémantique des fichiers de \textsc{rom} et des directives d'entrées.
+\subsection{The operating system}
 
-\end{document}
\ No newline at end of file
+\end{document}