From 818f81108fa30cd5a90c99df955f811fed043993 Mon Sep 17 00:00:00 2001 From: Alex AUVOLAT Date: Wed, 6 Nov 2013 19:22:00 +0100 Subject: Documented the C simulator in the README file ; added a test file. --- README | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 143 insertions(+), 17 deletions(-) (limited to 'README') diff --git a/README b/README index 43a4ebb..9235b1a 100644 --- a/README +++ b/README @@ -1,10 +1,12 @@ - Système Digital 2013-2014 Cours J.Vuillemin, TD T.Bourke Alex AUVOLAT (Info 2013) +Introduction +============ + Contents of the repository : ---------------------------- @@ -13,32 +15,48 @@ sched/ Input : a netlist. Output : a netlist with topologically sorted operators 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). $ cd sched/ $ ocamlbuild main.byte -camlsim/ - A circuit simulator written in OCaml. - This program does NOT do the scheduling. The netlist must be passed through sched/ first. - $ cd camlsim/ - $ ocamlbuild simulator.byte - csim/ A circuit simulator written in C. This program does NOT do the scheduling. - This program does NOT read a netlist, it reads a specifically formatted dumbed-down netlist, that - is output by the scheduler. + This program does NOT read a netlist, it reads a specifically formatted + dumbed-down netlist, that is output by the scheduler. $ cd csim $ make +camlsim/ + A circuit simulator written in OCaml. + This program does NOT do the scheduling. The netlist must be passed through + the scheduler first. + This program is *highly incomplete* and not recomended for real use.. + $ cd camlsim/ + $ ocamlbuild simulator.byte + minijazz/ - The MiniJazz compiler (not our doing). + The MiniJazz compiler (given by the teachers). *.pdf Documentation about the project. -CONVENTION FOR BINARY VALUES +REFERENCES +---------- + + - Computer organization and design : the hardware/software interface + 4th ed + Chapters 2 to 4 + + + +INTERNALS +========= + +Convention for binary values ---------------------------- /!\ This convention is contrary to the one used in the example file nadder.mj @@ -49,15 +67,123 @@ The bit array [a_0 a_1 a_2 ... a_n-1] represents the decimal number : When represented in binary, we write the bits in the order : a_0 a_1 a_2 ... a_n-1 +Even though the normal notation for a binary number is : + a_n-1 a_n-2 ... a_0 /!\ BINARY NUMBERS ARE WRITTEN REVERSE ! +What we call a shift-left does a left shift on the representation as a binary +number, but we use the reverse notation here. Therefore in the ALU, the shift-left +should actually right-shift the bits when they are seen in the order a0, a1, ... + +The right shift is also inverted. +- left shift -> right shift +- right shift -> left shift +- left shift logical -> rigth shift logical + + +The dumbed-down netlist format +------------------------------ + +The C simulator does NOT read a properly formatted netlist, but only a file +representing it written in a simple format, that can be parsed with only calls +to `scanf`. The file is organized as follows : + + + + + + + + +*1 : this section contains for each variable a line in the format : + + +In the rest of the files, the variables are referenced by their position in the +list given in *1 (the first line gives variable #0, etc.) + +*2 : these section contain one line : + [ ...] + +*3 : this section contains one line for each equation, in the following format : + [ ...] + +Table of equation types : + +Type# Desc Arguments +0 Arg +1 Reg +2 Not +3 Binop +4 Mux +5 Rom +6 Ram + +7 Concat +8 Slice +9 Select + +An argument ( or ) can be either a binary value, represented by the +bits in standard order defined above, either a reference to another variable, +with the syntax $ + +*4 : The operators are : +0 OR +1 XOR +2 AND +3 NAND + +This syntax is formalized by the reference implementation provided in the source +file csim/load.h. + +TODO : to simplify the internals, create an intermediate format where can +be nothing but a reference to another variable. All constants will then have to +be assigned to a constant-type variable that can be counted among the inputs (or +whatever - anyway, no need to recalculate them at every iteration). + + +The Input/Output format +----------------------- + +The C simulator is capable of reading inputs for each step from a file (by +default stdin, but can be redirected from a file using the -in option) and of +writing the outputs at each step to a file (by default stdout, but can be +redirected with -out). + +The input format is extremely straightforward : at each step, read a line +containing for each input variable, *in the order given in the program file*, +either a binary value (represented by a series of bits given in the standard +order), either a decimal value prefixed with a slash (/), which is then +converted to binary according to the standard representation defined above. + +The output format contains at each step one line for each output variable, in +the format : +\t\t +The output contains an empty line at the end of every cycle. + + +How ROMs are handled +-------------------- + +The MiniJazz language has many flaws, and one is the impossibility to specify +what is to be loaded in a ROM. One possibility (not implemented yet) would be +that each ROM-type equation uses data from a file which is found by looking at +the name of the variable that is read from the ROM. For example, if we have : + decode7_128 = ROM 4 7 _l_42_122 +which is a possible output for the MiniJazz compiler, and if the simulator is +provided with the command-line argument : + -rom decode7 path/to/decode7.rom +then the compiler will detect the prefix `decode7` in the variable name +decode7_128, and use the ROM from the file specified on the command line. + +Suggested format for the ROM files : + +
+ + +The data is composed of 2^(address width) values separated by spaces. If they +have no prefix, they are read as binary. If they have a / prefix, they are read +as decimal (this enables the use of whichever representation is preferred). -REFERENCES ----------- - - - Computer organization and design : the hardware/software interface - 4th ed - Chapters 2 to 4 -- cgit v1.2.3