Document programs ; better time support in monitor.

1 files changed, 69 insertions, 20 deletions

diff --git a/README b/README
index 7523ba5..1d1be18 100644
--- a/README
+++ b/README
@@ -2,6 +2,8 @@ Système Digital 2013-2014
 Cours J.Vuillemin, TD T.Bourke
 
 Alex AUVOLAT (Info 2013)
+Émile ENGUEHARD (Info 2013)
+Jonathan LAURENT (Info 2013)
 
 
 Introduction
@@ -14,11 +16,11 @@ sched/
     A scheduler for netlists.
     Input : a netlist.
     Output : a netlist with topologically sorted operators
-     plus a dumbed-down version for input to the C circuit simulator
+        plus a dumbed-down version for input to the C circuit simulator
     This program is also capable of a few optimisation (usually reduces netlist
-    size by 1/4 or 1/3).
+    size by 1/3 or better).
     $ cd sched/
-    $ ocamlbuild main.byte
+    $ make
 
 csim/
     A circuit simulator written in C.
@@ -27,12 +29,36 @@ csim/
     dumbed-down netlist, that is output by the scheduler.
     $ cd csim/
     $ make
+    Command-line arguments are detailed if the simulator is run with no arguments.
 
-minijazz/
-    The MiniJazz compiler (given by the teachers).
+cpu/
+    A CPU circuit designed in `plan_micro.pdf`.
+    The netlist for the CPU is generated by Caml code (and not MiniJazz code),
+    therefore this directory also contains Caml files for generating netlists
+    with Caml code (see `netlist_gen.mli` and `example_cpu.ml` for usage example).
+    
+monitor/
+    A C program used to monitor the simulator. The monitor has many functionnalities :
+    - Shows input and output at every step on a nice screen
+    - Ticking (every second or at every step)
+    - Running the simulator manually, at fixed frequency, or at maximum speed
+    - Serial input/output with simulated CPU
+    - 7-bar digit display based on simulator output
+    $ cd monitor/
+    $ make
+    Command-line arguments are in the format :
+        <simulator path> [<arguments for simulator> ...]
 
 tests/
-    Various test files.
+    Various test circuits (written in MiniJazz).
+    For file a.mj, type :
+    $ make a.sim
+    to compile and run the simulator on that file, and type :
+    $ make a.mon
+    to compile and run it with the monitor (better !)
+
+minijazz/
+    The MiniJazz compiler (given by the teachers).
 
 *.pdf
     Documentation about the project.
@@ -47,12 +73,34 @@ REFERENCES
     Chapters 2 to 4
 
 
+HOW TO RUN THE CPU
+==================
 
-INTERNALS
-=========
+Compile the scheduler :
 
-Convention for binary values
-----------------------------
+    $ cd sched/; make; cd ..
+
+Compile the monitor :
+
+    $ cd monitor/; make; cd ..
+
+Run the CPU with the monitor :
+
+    $ cd cpu/; make
+
+You are now in the main screen of the monitor. The following commands are usefull :
+
+    (empty command)             Execute one step of simulator
+    q                           Exit simulator
+    a                           Run simulator at max speed
+    f <freq>                    Run simulator at given frequency (in Hz)
+    t <input#>                  Send ticks every second on selected input
+
+Other commands are documented in `monitor/mon.c`
+
+
+CONVENTION FOR BINARY VALUES
+============================
 
 /!\ This convention is contrary to the one used in the example file nadder.mj
     (Therefore I have modified that file...)
@@ -77,6 +125,9 @@ The right shift is also inverted.
 - left shift logical -> rigth shift logical
 
 
+SIMULATOR INTERNALS
+===================
+
 The dumbed-down netlist format (OLD FORMAT)
 -------------------------------------------
 
@@ -204,6 +255,11 @@ the format :
 <variable name>\t<binary representation>\t<decimal representation>
 The output contains an empty line at the end of every cycle.
 
+When the simulator is launched, it sends an output describing the I/O mechanism
+of the simulated circuit :
+<number of inputs> <number of outputs>\n
+[for each input : <input size> <input name>\n]
+
 
 How ROMs are handled
 --------------------
@@ -241,19 +297,12 @@ not defined in the ROM file) will be considered zeroes.
 
 
 
-TODO
-----
-
-- More advanced commands for the simulator (cf Jonathan's simulator)
-
 NEXT STEPS
 ----------
 
-- Define convention for processor input/output
-- Code UI
-- How can we generate netlists with ocaml code ?
-- Code processor
-
+- Finish ALU
+- Code assembler
+- Code basic OS for the CPU