| .. _odin_II: |
| |
| ############# |
| Odin II |
| ############# |
| |
| Odin II is used for logic synthesis and elaboration, converting a subset of the Verilog Hardware Description Language (HDL) into a BLIF netlist. |
| |
| .. seealso:: :cite:`jamieson_odin_II` |
| |
| ************* |
| INSTALL |
| ************* |
| |
| ============= |
| Prerequisites |
| ============= |
| |
| 1. ctags |
| 2. bison |
| 3. flex |
| 4. gcc 5.x |
| 5. cmake 2.8.12 (minimum version) |
| 6. time |
| 7. cairo |
| |
| =========== |
| Build |
| =========== |
| |
| To build you may use the Makefile wrapper in the ODIN_ROOT ``make build`` |
| To build with debug symbols you may use the Makefile wrapper in the ODIN_ROOT ``make debug`` |
| |
| .. note:: |
| ODIN uses CMake as it's build system. CMake provides a protable cross-platform build systems with many useful features. |
| For unix-like systems we provide a wrapper Makefile which supports the traditional make and make clean commands, |
| but calls CMake behind the scenes. |
| |
| .. warning:: |
| After you build Odin, please run from the ODIN_ROOT ``make test`` |
| This will simulate, and verify all of the included microbenchmark circuits to ensure that Odin is working correctly on your system. |
| |
| |
| |
| ************* |
| USAGE |
| ************* |
| |
| ./odin_II [args] |
| |
| =============== |
| Required [args] |
| =============== |
| |
| .. list-table:: |
| |
| * - ``-c`` |
| - <XML Configuration File> |
| - fpga_architecture_file.xml format is specified from VPR |
| * - ``-V`` |
| - <Verilog HDL File> |
| - You may specify multiple verilog HDL files for synthesis |
| * - ``-b`` |
| - <BLIF File> |
| - |
| |
| =============== |
| Optional [args] |
| =============== |
| |
| .. list-table:: |
| |
| * - ``-o`` |
| - <output file> |
| - full output path and file name for the blif output file |
| * - ``-a`` |
| - <architecture file> |
| - an FPGA architecture file in VPR format to map to |
| * - ``-G`` |
| - |
| - Output netlist graph in GraphViz viewable .dot format. (net.dot, opens with dotty) |
| * - ``-A`` |
| - |
| - Output AST graph in in GraphViz viewable .dot format. |
| * - ``-W`` |
| - |
| - Print all warnings. (Can be substantial.) |
| * - ``-h`` |
| - |
| - Print help |
| |
| |
| =========== |
| Simulation |
| =========== |
| |
| .. note:: |
| |
| Simulation always produces files: |
| |
| - input_vectors |
| - output_vectors |
| - test.do (ModelSim) |
| |
| Activate Simulation with [args] |
| ******************************* |
| |
| .. list-table:: |
| |
| * - ``-g`` |
| - <Number of random test vectors> |
| - will simulate the generated netlist with the entered number of clock cycles using pseudo-random test vectors. These vectors and the resulting output vectors are written to "input_vectors" and "output_vectors" respectively. You can supply a predefined input vector using ``-t`` |
| * - ``-L`` |
| - <Comma-separated list> |
| - Comma-separated list of primary inputs to hold high at cycle 0, and low for all subsequent cycles. |
| * - ``-3`` |
| - |
| - Generate three valued logic. (Default is binary.) |
| * - ``-t`` |
| - <input vector file> |
| - Supply a predefined input vector file |
| * - ``-U0`` |
| - |
| - initial register value to 0 |
| * - ``-U1`` |
| - |
| - initial register value to 1 |
| * - ``-UX`` |
| - |
| - initial register value to X(unknown) (DEFAULT) |
| |
| Simulation Optional [args] |
| ************************** |
| |
| .. list-table:: |
| |
| * - ``-T`` |
| - <output vector file> |
| - The output vectors is verified against the supplied predefined output vector file |
| * - ``-E`` |
| - |
| - Output after both edges of the clock. (Default is to output only after the falling edge.) |
| * - ``-R`` |
| - |
| - Output after rising edge of the clock only. (Default is to output only after the falling edge.) |
| * - ``-p`` |
| - <Comma-separated list> |
| - Comma-separated list of additional pins/nodes to monitor during simulation. (view NOTES) |
| |
| =========== |
| NOTES |
| =========== |
| |
| Example for ``-p``: |
| ******************* |
| |
| .. list-table:: |
| |
| * - ``-p input~0,input~1`` |
| - monitors pin 0 and 1 of input |
| * - ``-p input`` |
| - monitors all pins of input as a single port |
| * - ``-p input~`` |
| - monitors all pins of input as separate ports. (split) |
| |
| .. note:: |
| |
| Matching for ``-p`` is done via strstr so general strings will match all similar pins and nodes. (Eg: FF_NODE will create a single port with all flipflops) |
| |
| |
| Examples .xml configuration file for ``-c`` |
| ******************************************* |
| |
| .. code-block:: xml |
| |
| <config> |
| <verilog_files> |
| <!-- Way of specifying multiple files in a project! --> |
| <verilog_file>verilog_file.v</verilog_file> |
| </verilog_files> |
| <output> |
| <!-- These are the output flags for the project --> |
| <output_type>blif</output_type> |
| <output_path_and_name>./output_file.blif</output_path_and_name> |
| <target> |
| <!-- This is the target device the output is being built for --> |
| <arch_file>fpga_architecture_file.xml</arch_file> |
| </target> |
| </output> |
| <optimizations> |
| <!-- This is where the optimization flags go --> |
| </optimizations> |
| <debug_outputs> |
| <!-- Various debug options --> |
| <debug_output_path>.</debug_output_path> |
| <output_ast_graphs>1</output_ast_graphs> |
| <output_netlist_graphs>1</output_netlist_graphs> |
| </debug_outputs> |
| </config> |
| |
| .. note:: |
| Hard blocks can be simulated; given a hardblock named ``block`` in the architecture file with an instance of it named ``instance`` in the verilog file, write a C method with signature defined in ``SRC/sim_block.h`` and compile it with an output filename of ``block+instance.so`` in the directory you plan to invoke Odin_II from. |
| |
| When compiling the file, you'll need to specify the following arguments to the compiler (assuming that you're in the SANBOX directory): |
| |
| ``cc -I../../libarchfpga_6/include/ -L../../libarchfpga_6 -lvpr_6 -lm --shared -o block+instance.so block.c.`` |
| |
| If the netlist generated by Odin II contains the definition of a hardblock which doesn't have a shared object file defined for it in the working directory, Odin II will not work if you specify it to use the simulator with the ``-g`` or ``-t`` options. |
| |
| .. warning:: |
| Use of static memory within the simulation code necessitates compiling a distinct shared object file for each instance of the block you wish to simulate. The method signature the simulator expects contains only int and int[] parameters, leaving the code provided to simulate the hard blokc agnostic of the internal Odin II data structures. However, a cycle parameter is included to provide researchers with the ability to delay results of operations performed by the simulation code. |
| |
| Examples vector file for ``-t`` or ``-T`` |
| ***************************************** |
| |
| .. code-block:: none |
| |
| # Example vector file |
| intput_1 input_2 output_1 output_2 output_3 |
| # Comment |
| 0 0XA 1 0XD 1101 |
| |
| .. note:: |
| Each line represents a vector. Each value must be specified in binary or hex. Comments may be included by placing an # at the start of the line. Blank lines are ignored. Values may be separated by non-newline whitespace. (tabs and spaces) Hex values must be prefixed with 0X. |
| |
| Each line in the vector file represents one cycle, or one falling edge and one rising edge. Input vectors are read on a falling edge, while output vectors are written on a rising edge. |
| |
| |
| Verilog Synthesizable Keyword Support: |
| ********************************* |
| |
| +-------------------+------------------+---------------------+--------------------+ |
| | Supported Keyword | NOT Sup. Keyword | Supported Operators | NOT Sup. Operators | |
| +-------------------+------------------+---------------------+--------------------+ |
| | @() | automatic | != | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | @* | deassign | !== | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | `define | disable | == | \>\>\> | |
| +-------------------+------------------+---------------------+--------------------+ |
| | always | edge | === | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | and | endtask | =\> | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | assign | forever | ** | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | case | task | ^~ | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | defparam | repeat | <<< | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | end | signed | \>= | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | endfunction | task | || | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | endmodule | generate | ~& | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | begin | genvar | && | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | default | | << | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | else | | <= | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | endcase | | >> | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | endspecify | | ~^ | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | for | | ~| | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | function | | $clog() | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | if | | -: | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | inout | | +: | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | input | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | integer | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | localparam | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | module | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | nand | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | negedge | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | nor | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | not | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | or | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | output | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | parameter | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | posedge | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | reg | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | specify | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | while | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | wire | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | xnor | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | xor | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | macromodule | | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| |
| Verilog Syntax support: |
| ********************************* |
| |
| inline port declaration in the module declaration |
| i.e: |
| |
| .. code-block:: verilog |
| |
| module a(input clk) |
| ... |
| endmodule |
| |
| |
| Verilog NON-Synthesizable Keyword Support: |
| ********************************* |
| |
| +-------------------+------------------+---------------------+--------------------+ |
| | Supported Keyword | NOT Sup. Keyword | Supported Operators | NOT Sup. Operators | |
| +-------------------+------------------+---------------------+--------------------+ |
| | initial | casex | | &&& | |
| +-------------------+------------------+---------------------+--------------------+ |
| | specparam | casez | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | | endprimitive | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | | endtable | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | | event | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | | force | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | | fork | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | | join | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | | primitive | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | | release | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | | table | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | | time | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| | | wait | | | |
| +-------------------+------------------+---------------------+--------------------+ |
| |
| |
| Verilog Gate Level Modeling Support: |
| ********************************* |
| |
| +-------------------+------------------+ |
| | Supported Keyword | NOT Sup. Keyword | |
| +-------------------+------------------+ |
| | | buf | |
| +-------------------+------------------+ |
| | | bufif0 | |
| +-------------------+------------------+ |
| | | bufif1 | |
| +-------------------+------------------+ |
| | | cmos | |
| +-------------------+------------------+ |
| | | highz0 | |
| +-------------------+------------------+ |
| | | highz0 | |
| +-------------------+------------------+ |
| | | highz1 | |
| +-------------------+------------------+ |
| | | highz1 | |
| +-------------------+------------------+ |
| | | large | |
| +-------------------+------------------+ |
| | | medium | |
| +-------------------+------------------+ |
| | | nmos | |
| +-------------------+------------------+ |
| | | notif0 | |
| +-------------------+------------------+ |
| | | notif1 | |
| +-------------------+------------------+ |
| | | pmos | |
| +-------------------+------------------+ |
| | | pull0 | |
| +-------------------+------------------+ |
| | | pull1 | |
| +-------------------+------------------+ |
| | | pulldown | |
| +-------------------+------------------+ |
| | | pullup | |
| +-------------------+------------------+ |
| | | rcmos | |
| +-------------------+------------------+ |
| | | rnmos | |
| +-------------------+------------------+ |
| | | rpmos | |
| +-------------------+------------------+ |
| | | rtran | |
| +-------------------+------------------+ |
| | | rtranif0 | |
| +-------------------+------------------+ |
| | | rtranif1 | |
| +-------------------+------------------+ |
| | | scalared | |
| +-------------------+------------------+ |
| | | small | |
| +-------------------+------------------+ |
| | | strong0 | |
| +-------------------+------------------+ |
| | | strong0 | |
| +-------------------+------------------+ |
| | | strong1 | |
| +-------------------+------------------+ |
| | | strong1 | |
| +-------------------+------------------+ |
| | | supply0 | |
| +-------------------+------------------+ |
| | | supply1 | |
| +-------------------+------------------+ |
| | | tran | |
| +-------------------+------------------+ |
| | | tranif0 | |
| +-------------------+------------------+ |
| | | tranif1 | |
| +-------------------+------------------+ |
| | | tri | |
| +-------------------+------------------+ |
| | | tri0 | |
| +-------------------+------------------+ |
| | | tri1 | |
| +-------------------+------------------+ |
| | | triand | |
| +-------------------+------------------+ |
| | | trior | |
| +-------------------+------------------+ |
| | | vectored | |
| +-------------------+------------------+ |
| | | wand | |
| +-------------------+------------------+ |
| | | weak0 | |
| +-------------------+------------------+ |
| | | weak0 | |
| +-------------------+------------------+ |
| | | weak1 | |
| +-------------------+------------------+ |
| | | weak1 | |
| +-------------------+------------------+ |
| | | wor | |
| +-------------------+------------------+ |
| |
| ******************* |
| DOCUMENTING ODIN II |
| ******************* |
| |
| Any new command line options added to Odin II should be fully documented by |
| the print_usage() function within odin_ii.c before checking in the changes. |
| |
| *************** |
| TESTING ODIN II |
| *************** |
| |
| The verify_odin.sh scripts simulate the microbenchmarks and a larger set of benchmark |
| circuits. These scripts use simulation results which have been verified |
| against ModelSim. |
| |
| After you build Odin II, run verify_odin.sh to ensure that |
| everything is working correctly on your system. Unlike the |
| verify_regression_tests.sh script, verify_odin.sh also |
| simulates the blif output, as well as simulating the verilog with and |
| without the architecture file. |
| |
| Before checking in any changes to Odin II, please run both of these |
| scripts to ensure that both of these scripts execute correctly. If there |
| is a failure, use ModelSim to verify that the failure is within Odin II |
| and not a faulty regression test. The Odin II simulator will produce |
| a test.do file containing clock and input vector information for ModelSim. |
| |
| When additional circuits are found to agree with ModelSim, they should |
| be added to these test sets. When new features are added to Odin II, new |
| microbenchmarks should be developed which test those features for |
| regression. Use existing circuits as a template for the addition of |
| new circuits. |
| |
| ****************************** |
| USING MODELSIM TO TEST ODIN II |
| ****************************** |
| |
| ModelSim may be installed as part of the Quartus II Web Edition IDE. Load |
| the Verilog circuit into a new project in ModelSim. Compile the circuit, |
| and load the resulting library for simulation. |
| |
| You may use random vectors via the -g option, |
| or specify your own input vectors using the -t option. When simulation is |
| complete, load the resulting test.do file into your ModelSim project and |
| execute it. You may now directly compare the vectors in the output_vectors |
| file with those produced by ModelSim. |
| |
| To add the verified vectors and circuit to an existing test set, move the |
| verilog file (eg: test_circuit.v) to the test set folder. Next, move the |
| input_vectors file to the test set folder, and rename it test_circuit_input. |
| Finally, move the output_vectors file to the test set folder and rename |
| it test_circuit_output. |
| |
| ************* |
| CONTACT |
| ************* |
| |
| jamieson dot peter at gmail dot com |
| ken at unb dot ca |
| - We will service all requests as timely as possible, but |
| please explain the problem with enough detail to help. |
