Un peu de doc

Makefile

-RAPPORT=RAPPORT
+MD_SOURCES=$(wildcard *.md)
 BUILD_DIR=_CPU_build
 TEST_DIR=_test_build
 SRC=$(wildcard cpu/src/*.mj)
 CPU=$(BUILD_DIR)/cpu
 
-.PHONY: simulator all minijazz fullclean test clean pre_build
+.PHONY: simulator all minijazz fullclean test clean pre_build pdf
 
-all: $(RAPPORT).pdf $(CPU).net
+all: $(CPU).net pdf
 
 simulator:
 	@echo "==> Building simulator"
@@ -35,14 +35,16 @@ test: minijazz simulator pre_build
 	@echo "==> Building asm tests"
 	cd simulator && make asm
 	@echo "==> Running asm tests"
-	./test_asm.sh
+	test/test_asm.sh
 	@echo "==> Running minijazz tests"
-	./test_mj.sh
+	test/test_mj.sh
+
+pdf: $(MD_SOURCES:.md=.pdf)
 
 %.pdf: %.md
-	@echo "==> Trying to build $(RAPPORT).pdf using pandoc"
+	@echo "==> Trying to build $@ using pandoc"
 	@(pandoc -sS -t latex -o $@ $< 2>/dev/null && echo "Success") \
-		|| echo "Failed, read $(RAPPORT).md instead"
+		|| echo "Failed, read $< instead"
 
 
 clean:
@@ -52,7 +54,7 @@ clean:
 	rm -f test/mj/*.net
 
 fullclean: clean
-	rm -f $(RAPPORT).pdf
+	rm -f *.pdf
 	cd simulator && make clean
 	cd minijazz && make clean
 	cd cpu && make clean

README.md

+# Projet du cours de système digital 2016-2017
+
+
+## HOWTO
+
+La commande pour compiler le processeur est `make` il faut ensuite le lancer à
+l'aide de `make run` (tourne dans le vide) ou 
+`./run.sh _CPU_build/cpu.net <asm file>` où `<asm file>` désigne le code
+assembleur à charger dans la ROM avant l'exécution.
+
+### Compiler séparément les différentes parties
+
+Voici la liste des commandes makefile disponibles :
+
+- `make`, `make run` : cf ci dessus.
+- `make simulator` : compile uniquement le simulateur.
+- `make minijazz` : compile uniquement le compilateur minijazz.
+- `make pre_build` assemble les sources minijazz en un seul fichier.
+- `make test` : lance une batterie de tests, cf plus bas.
+- `make pdf` : génère un pdf à partir de `RAPPORT.md` et `README.md` à l'aide de
+  pandoc si pandoc est disponible. Ces fichiers sont lisibles tels quels à
+  défaut.
+- `make clean` : nettoie le dépôt des fichiers générés par `make` et
+  `make test` uniquement.
+- `make fullclean` : Nettoie tout le dépôt, y compris les fichiers générés par
+  ocamlbuild et le pdfs.
+
+
+---
+
+
+## Structure du dépôt
+
+- `simulator/` : les sources du simulateur.
+    - Un parseur de netlist
+    - Un parseur d'assembleur MIPS
+    - L'ordonnancement et l'exécution du circuit
+- `minijazz/` : le compilateur minijazz vers netlist.
+- `cpu/` : le code minijazz du processeur lui même.
+    - Les différentes parties du processeur sont sous `cpu/src/`. Le point
+      d'entrée est dans le fichier `main.mj`.
+    - Un script Ocaml qui assemble les différents morceaux du CPU en un seul
+      fichier. Cf la section suivante.
+- `test/` : des tests unitaires plus ou moins exhaustifs.
+
+Les dossiers `_CPU_build/` et `_test_build/` sont générés automatiquement pour y
+stocker les fichiers générés lors de la compilation.
+
+Enfin, le script `run.sh` sert à lancer le simulateur sur un programme
+assembleur donné en entrée. Usage : `run.sh <file.net> [<asm file>]`
+
+## Système de build custom pour minijazz
+
+Le script `cpu/pre_build.ml` sert à séparer le code du CPU en plusieurs fichiers
+(dans `cpu/src/`). Ces fichiers doivent contenir sur leurs premières lignes la
+liste des fichiers dont ils dépendent au format `require foo` (pour signifier
+"dépend de `foo.mj`"). Le graphe de dépendance des différents morceaux de
+circuit et ensuite construit et les fichiers sont concaténés dans le bon ordre. 
+
+**Attention** : ce n'est **pas** un vrai système de module au sens où il n'y a
+pas de namespace : si deux fichiers génèrent des blocs avec le même nom il y
+aura conflit.
+
+
+---
+
+
+## Tests
+
+Le dossier `test/` contient trois types de tests :
+
+- Des fichiers `.net` pour tester le simulateur (utilisés lors de l'écriture du
+  simulateur, plus utiles désormais).
+- Des fichiers `.mj` avec pour chacun, des fichiers `.in` et `.out` qui
+  correspondent respectivement à des entrées données au circuit à chaque cycle
+  et les sorties attendues correspondantes. Le script `test_mj.sh` teste ces
+  circuits un à un sur les entrées spécifiées et vérifie la sortie.
+- Des fichiers assembleur. Actuellement le script `test_asm.sh` vérifie
+  uniquement que les programmes sont chargés sans incident dans la ROM. À terme
+  il faudrait que le CPU soit lancé sur ces programmes et qu'on vérifie que
+  l'exécution se déroule correctement.
+
+La commande `make test` permet de lancer tous les tests et d'afficher le
+résultat.