diff --git a/ODIN_II/README.md b/ODIN_II/README.md new file mode 100644 index 00000000000..147f18a582e --- /dev/null +++ b/ODIN_II/README.md @@ -0,0 +1,15 @@ +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. + +----------------- + +* **[Quick Start](../doc/src/odin/quickstart.md)** +* **[User Guide](../doc/src/odin/user_guide.md)** +* **[Verilog Support](../doc/src/odin/verilog_support.md)** +* **Developper guide** + * [Contributing](../doc/src/odin/dev_guide/contributing) + * [Regression Tests](../doc/src/odin/dev_guide/regression_test) + * [Regression Tool](../doc/src/odin/dev_guide/verify_script) + * [Validating Tests](../doc/src/odin/dev_guide/testing) diff --git a/ODIN_II/README.rst b/ODIN_II/README.rst deleted file mode 120000 index 3b96a58254e..00000000000 --- a/ODIN_II/README.rst +++ /dev/null @@ -1 +0,0 @@ -../doc/src/odin/index.rst \ No newline at end of file diff --git a/doc/src/odin/dev_guide/contributing.md b/doc/src/odin/dev_guide/contributing.md new file mode 100644 index 00000000000..95615533a92 --- /dev/null +++ b/doc/src/odin/dev_guide/contributing.md @@ -0,0 +1,37 @@ +# Contributing + +The Odin II team welcomes outside help from anyone interested. +To fix issues or add a new feature submit a PR or WIP PR following the provided guidelines. + +## Creating a Pull Request (PR) + +**Important** Before creating a Pull Request (PR), if it is a bug you have happened upon and intend to fix make sure you create an issue beforhand. + +Pull requests are intended to correct bugs and improve Odin's performance. +To create a pull request, clone the vtr-verilog-rooting repository and branch from the master. +Make changes to the branch that improve Odin II and correct the bug. +**Important** In addition to correcting the bug, it is required that test cases (benchmarks) are created that reproduce the issue and are included in the regression tests. +An example of a good test case could be the benchmark found in the "Issue" being addressed. +The results of these new tests need to be regenerate. See [regression tests](./regression_tests) for further instruction. +Push these changes to the cloned repository and create the pull request. +Add a description of the changes made and reference the "issue" that it corrects. There is a template provided on GitHub. + +### Creating a "Work in progress" (WIP) PR + +**Important** Before creating a WIP PR, if it is a bug you have happened upon and intend to fix make sure you create an issue beforhand. + +A "work in progress" PR is a pull request that isn't complete or ready to be merged. +It is intended to demonstrate that an Issue is being addressed and indicates to other developpers that they don't need to fix it. +Creating a WIP PR is similar to a regular PR with a few adjustements. +First, clone the vtr-verilog-rooting repository and branch from the master. +Make changes to that branch. +Then, create a pull request with that branch and **include WIP in the title.** +This will automatically indicate that this PR is not ready to be merged. +Continue to work on the branch, pushing the commits regularly. +Like a PR, test cases are also needed to be included through the use of benchmarks. +See [regression tests](./regression_tests) for further instruction. + +### Formating + +Odin II shares the same contributing philosophy as [VPR](https://docs.verilogtorouting.org/en/latest/dev/contributing/contributing/). +Most importantly PRs will be rejected if they do not respect the coding standard: see [VPRs coding standard](https://docs.verilogtorouting.org/en/latest/dev/developing/#code-formatting) diff --git a/doc/src/odin/dev_guide/regression_test.md b/doc/src/odin/dev_guide/regression_test.md new file mode 100644 index 00000000000..f48fd313dbc --- /dev/null +++ b/doc/src/odin/dev_guide/regression_test.md @@ -0,0 +1,388 @@ +# Regression Tests + +Regression tests are tests that are repeatedly executed to assess functionality. +Each regression test targets a specific function of Odin II. +There are two main components of a regression test; benchmarks and a configuration file. +The benchmarks are comprised of verilog files, input vector files and output vector files. +The configuration file calls upon each benchmark and synthesizes them with different architectures. +The current regression tests of Odin II can be found in regression_test/benchmarks. + +## Benchmarks + +Benchmarks are used to test the functionality of Odin II and ensure that it runs properly. +Benchmarks of Odin II can be found in regression_test/benchmarks/verilog/any_folder. +Each benchmark is comprised of a verilog file, an input vector file, and an output vector file. +They are called upon during regression tests and synthesized with different architectures to be compared against the expected results. +These tests are usefull for developers to test the functionality of Odin II after implementing changes. +The command `make test` runs through all these tests, comparing the results to previously generated results, and should be run through when first installing. + +### Unit Benchmarks + +Unit Benchmarks are the simplest of benchmarks. They are meant to isolate different functions of Odin II. +The goal is that if it does not function properly, the error can be traced back to the function being tested. +This cannot always be achieved as different functions depend on others to work properly. +It is ideal that these benchmarks test bit size capacity, errorenous cases, as well as standards set by the IEEE Standard for Verilog® Hardware Description Language - 2005. + +### Micro Benchmarks + +Micro benchmark's are precise, like unit benchmarks, however are more syntactic. +They are meant to isolate the behaviour of different functions. +They trace the behaviour of functions to ensure they adhere to the IEEE Standard for Verilog® Hardware Description Language - 2005. +Like micro benchmarks, they should check errorenous cases and behavioural standards et by the IEEE Standard for Verilog® Hardware Description Language - 2005. + +### Macro Benchmarks + +Macro benchmarks are more realistic tests that incorporate multiple functions of Odin II. +They are intended to simulate real-user behaviour to ensure that functions work together properly. +These tests are designed to test things like syntax and more complicated standards set by the IEEE Standard for Verilog® Hardware Description Language - 2005. + +### External Benchmarks + +External Benchmarks are benchmarks created by outside users to the project. +It is possible to pull an outside directory and build them on the fly thus creating a benchmark for Odin II. + +## Creating Regression tests + +### New Regression Test Checklist + +* Create benchmarks [here](#creating-benchmarks) +* Create configuration file [here](#creating-a-configuration-file) +* Create a folder in the task directory for the configuration file [here](#creating-a-task) +* Generate the results [here](#regenerating-results) +* Add the task to a suite (large suite if generating the results takes longer than 3 minutes, otherwise put in light suite) [here](#creating-a-suite) +* Update the documentation by providing a summary in Regression Test Summary section and updating the Directory tree [here](#regression-test-summaries) + +### New Benchmarks added to Regression Test Checklist + +* Create benchmarks and add them to the correct regression test folder found in the benchmark/verilog directory [here](#creating-benchmarks) (There is a description of each regression test [here](#regression-test-summaries)) +* Regenerate the results [here](#regenerating-results) + +### Include + +* verilog file +* input vector file +* expected ouptut vector file +* configuration file (conditional) +* architecture file (optional) + +### Creating Benchmarks + +If only a few benchmarks are needed for a PR, simply add the benchmarks to the appropriate set of regression tests. +[The Regression Test Summary](#regression-test-summaries) summarizes the target of each regression test which may be helpful. + +The standard of naming the benchmarks are as follows: + +* verilog file: meaningful_title.v +* input vector file: meaningful_title_input +* output vector file: meaningful_title_output + +If the tests needed do not fit in an already existing set of regression tests or need certain architecture(s), create a seperate folder in the verilog directory and label appropriately. +Store the benchmarks in that folder. +Add the architecture (if it isn't one that already exists) to ../vtr_flow/arch. + +> **NOTE** +> +> If a benchmark fails and should pass, include a $display statement in the verilog file in the following format: +> +> `$display("Expect::FUNCTION < message >);` +> +> The function should be in all caps and state what is causing the issue. For instance, if else if was behaving incorrectly it should read ELSE_IF. The message +> should illustrate what should happen and perhaps a suggestion in where things are going wrong. + +### Creating a Configuration File + +A configuration file is only necessary if the benchmarks added are placed in a new folder. +The configuration file is where architectures and commands are specified for the synthesis of the benchmarks. +**The configuration file must be named task.conf.** +The following is an example of a standard task.conf (configuration) file: + +```bash +######################## +# benchmarks config +######################## + +# commands +regression_params=--include_default_arch +script_synthesis_params=--time_limit 3600s +script_simulation_params=--time_limit 3600s +simulation_params= -L reset rst -H we + +# setup the architecture (standard architectures already available) +archs_dir=../vtr_flow/arch/timing + +arch_list_add=k6_N10_40nm.xml +arch_list_add=k6_N10_mem32K_40nm.xml +arch_list_add=k6_frac_N10_frac_chain_mem32K_40nm.xml + +# setup the circuits +circuits_dir=regression_test/benchmark/verilog/ + +circuit_list_add=<verilog file group>/*.vh +circuit_list_add=<verilog file group>/*.v + + +synthesis_parse_file=regression_test/parse_result/conf/synth.toml +simulation_parse_file=regression_test/parse_result/conf/sim.toml +``` + +The following key = value are available for configuration files: + +| key |following argument | +|--------------------------|----------------------------------------------------| +|circuits_dir |< path/to/circuit/dir > | +|circuit_list_add |< circuit file path relative to [circuits_dir] > | +|archs_dir |< path/to/arch/dir > | +|arch_list_add |< architecture file path relative to [archs_dir] > | +|synthesis_parse_file |< path/to/parse/file > | +|simulation_parse_file |< path/to/parse/file > | +|script_synthesis_params | [see exec_wrapper.sh options] | +|script_simulation_params |[see exec_wrapper.sh options] | +|synthesis_params |[see Odin options] | +|simulation_params |[see Odin options] | +|regression_params |[see Regression Parameters bellow] + +Regression Parameters: + +* `--verbose` display error logs after batch of tests +* `--concat_circuit_list` concatenate the circuit list and pass it straight through to odin +* `--generate_bench` generate input and output vectors from scratch +* `--disable_simulation` disable the simulation for this task +* `--disable_parallel_jobs` disable running circuit/task pairs in parralel +* `--randomize` performs a dry run randomly to check the validity of the task and flow | +* `--regenerate_expectation`regenerates expectation and overrides thee expected value only if there's a mismatch | +* `--generate_expectation` generate the expectation and overrides the expectation file | + +### Creating a task + +The following diagram illustrates the structure of regression tests. +Each regression test needs a corresponding folder in the task directory containing the configuration file. +The \<task display name\> should have the same name as the verilog file group in the verilog directory. +This folder is where the synthesis results and simulation results will be stored. +The task diplay name and the verilog file group should share the same title. + +```bash +└── ODIN_II + └── regression_test + └── benchmark + ├── task + │ └── < task display name > + │ ├── [ simulation_result.json ] + │ ├── [ synthesis_result.json ] + │ └── task.conf + └── verilog + └── < verilog file group > + ├── *.v + └── *.vh +``` + +#### Creating a Complicated Task + +There are times where multiple configuration files are needed in a regression test due to different commands wanted or architectures. +The task cmd_line_args is an example of this. +If that is the case, each configuration file will still need its own folder, however these folder's should be placed in a parent folder. + +```bash +└── ODIN_II + └── regression_test + └── benchmark + ├── task + │ └── < parent task display name > + | ├── < task display name > + │ │ ├── [ simulation_result.json ] + │ │ ├── [ synthesis_result.json ] + | │ └── task.conf + │ └── < task display name > + │ . ├── [ simulation_result.json ] + │ . ├── [ synthesis_result.json ] + | . └── task.conf + └── verilog + └── < verilog file group > + ├── *.v + └── *.vh +``` + +#### Creating a Suite + +Suites are used to call multiple tasks at once. This is handy for regenerating results for multiple tasks. +In the diagram below you can see the structure of the suite. +The suite contains a configuration file that calls upon the different tasks **named task_list.conf**. + +```bash +└── ODIN_II + └── regression_test + └── benchmark + ├── suite + │ └── < suite display name > + | └── task_list.conf + ├── task + │ ├── < parent task display name > + | │ ├── < task display name > + │ │ │ ├── [ simulation_result.json ] + │ │ │ ├── [ synthesis_result.json ] + | │ │ └── task.conf + │ │ └── < task display name > + │ │ ├── [ simulation_result.json ] + │ │ ├── [ synthesis_result.json ] + | │ └── task.conf + │ └── < task display name > + │ ├── [ simulation_result.json ] + │ ├── [ synthesis_result.json ] + | └── task.conf + └── verilog + └── < verilog file group > + ├── *.v + └── *.vh +``` + +In the configuration file all that is required is to list the tasks to be included in the suite with the path. +For example, if the wanted suite was to call the binary task and the operators task, the configuration file would be as follows: + +```bash +regression_test/benchmark/task/operators +regression_test/benchmark/task/binary +``` + +For more examples of task_list.conf configuration files look at the already existing configuration files in the suites. + +### Regenerating Results + +Regenerating results is necessary if any regression test is changed (added benchmarks), if a regression test is added, or if a bug fix was implemented that changes the results of a regression test. +For all cases, it is necessary to regenerate the results of the task corresponding to said change. +The following commands illustrate how to do so: + +```shell +make sanitize +``` + +then: where N is the number of processors in the computer, and the path following -t ends with the same name as the folder you placed + +```shell +./verify_odin.sh -j N --regenerate_expectation -t regression_test/benchmark/task/<task_display_name> +``` + +> **NOTE** +> +> **DO NOT** run the `make sanitize` if regenerating the large test. It is probable that the computer will not have a enough ram to do so and it will take a long time. Instead run `make build` + +For more on regenerating results, refer to the [Verify Script](./verify_script.md) section. + +## Regression Test Summaries + +### Binary + +This regression test targets low level binary and unary logic gates. It tests the bit size capacity, as well as different syntaxes set in the verilog standard. + +### cmd_line_args + +This is a more complicated regression test that incorporates multiple child tasks. +It targets different commands available in Odin II. +Although it doesn't have a dedicated set of benchmarks in the verilog folder, the configuration files call on different preexisting benchmarks. + +### FIR + +FIR is an acronym for "Finite Impulse Response". +These benchmarks were sourced from [Layout Aware Optimization of High Speed Fixed Coefficient FIR Filters for FPGAs](http://kastner.ucsd.edu/fir-benchmarks/?fbclid=IwAR0sLk_qaBXfeCeDuzD2EWBrCJ_qGQd7rNISYPemU6u98F6CeFjWOMAM2NM). +They test a method of implementing high speed FIR filters on FPGAs discussed in the paper. + +### full + +The full regression test is designed to test real user behaviour. +It does this by simulating flip flop, muxes and other common uses of verilog. + +### large + +This regression test targets cases that require a lot of ram and time. + +### micro + +The micro regression tests targets hards blocks and pieces that can be easily instantiated in architectures. + +### opertators + +This regression test targets the functionality of different opertators. It checks bit size capacity and behaviour. + +### syntax + +The syntax regression tests targets syntactic behaviour. It checks that functions work cohesively together and adhere to the verilog standard. + +### Regression Tests Directory Tree + +```bash +benchmark + ├── suite + │   ├── full_suite + │   │   └── task_list.conf + │   ├── heavy_suite + │   │   └── task_list.conf + │   └── light_suite + │   └── task_list.conf + ├── task + │   ├── arch_sweep + │   │   ├── synthesis_result.json + │   │   └── task.conf + │   ├── binary + │   │   ├── simulation_result.json + │   │   ├── synthesis_result.json + │   │   └── task.conf + │   ├── cmd_line_args + │   │   ├── batch_simulation + │   │   │   ├── simulation_result.json + │   │   │   ├── synthesis_result.json + │   │   │   └── task.conf + │   │   ├── best_coverage + │   │   │   ├── simulation_result.json + │   │   │   ├── synthesis_result.json + │   │   │   └── task.conf + │   │   ├── coverage + │   │   │   ├── simulation_result.json + │   │   │   ├── synthesis_result.json + │   │   │   └── task.conf + │   │   ├── graphviz_ast + │   │   │   ├── synthesis_result.json + │   │   │   └── task.conf + │   │   ├── graphviz_netlist + │   │   │   ├── synthesis_result.json + │   │   │   └── task.conf + │   │   └── parallel_simulation + │   │   ├── simulation_result.json + │   │   ├── synthesis_result.json + │   │   └── task.conf + │   ├── FIR + │   │   ├── simulation_result.json + │   │   ├── synthesis_result.json + │   │   └── task.conf + │   ├── full + │   │   ├── simulation_result.json + │   │   ├── synthesis_result.json + │   │   └── task.conf + │   ├── large + │   │   ├── synthesis_result.json + │   │   └── task.conf + │   ├── micro + │   │   ├── simulation_result.json + │   │   ├── synthesis_result.json + │   │   └── task.conf + │   ├── operators + │   │   ├── simulation_result.json + │   │   ├── synthesis_result.json + │    │   └── task.conf + │   ├── syntax + │   │   ├── simulation_result.json + │    │   ├── synthesis_result.json + │    │   └── task.conf + │   └── vtr + │   └── task.conf + ├── third_party + │   └── SymbiFlow + │   ├── build.sh + │   └── task.mk + └── verilog + ├── binary + ├── ex1BT16_fir_20_input + ├── FIR + ├── full + ├── large + ├── micro + ├── operators + └── syntax +``` diff --git a/doc/src/odin/dev_guide/testing.md b/doc/src/odin/dev_guide/testing.md new file mode 100644 index 00000000000..780e57c42c7 --- /dev/null +++ b/doc/src/odin/dev_guide/testing.md @@ -0,0 +1,31 @@ +# TESTING ODIN II + +The verify_odin.sh script will 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 'make test' 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. +If it is a faulty regression test, make an [issue on GitHub](./reporting_bugs.md). +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 the regression tests. +When new features are added to Odin II, new microbenchmarks should be developed which test those features for regression. +This process is illustrated in the Developper Guide, in the Regression Tests section. + +## 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. diff --git a/doc/src/odin/dev_guide/verify_script.md b/doc/src/odin/dev_guide/verify_script.md new file mode 100644 index 00000000000..64293b7baf1 --- /dev/null +++ b/doc/src/odin/dev_guide/verify_script.md @@ -0,0 +1,90 @@ +# Verify Script + +The verify_odin.sh script is designed for generating regression test results. + +./verify_odin.sh [args] + +## Arguments + +*The tool requires a task to run hence `-t <task directory>` must be passed in + +| arg | equivalent form | Following argument | Description | +|-------|---------------------------|-------------------------------------|------------------------------------------------------------------------------------------------| +| `-t` | path to directory containing a test |The test types are a task.conf,task_list.conf or a predefined test | +| `-j` | `-- nb_of_process` | # of processors requested | This allows the user to choose how many processor are used in the computer, the default is 1 | +| `-d` | `--output_dir` | path to directory | This allows the user to change the directory of the run output | +| `-C` | `--config` | path to configuration file | This directs the compiler to a configuration file to append the configuration file of the test| +| `-t` | `--test` | path to directory containing a test | The test types are a task.conf,task_list.conf or a predefined test | +| `-h` | `--help` | N/A | Prints all possible commands and directives | +| `-g` | `--generate_bench` | N/A | Generates input and output vectors for test | +| `-o` | `--generate_output` | N/A | Generates output vector for test given its input vector | +| `-b` | `--build_config` | path to directory | Generates a configuration file for a given directory | +| `-c` | `--clean` | N/A | Clean temporary directory | +| `-f` | `--force_simulate` | N/A | Force the simulation to be executed regardless of the configuration file | +| N/A | `--override` | N/A | if a configuration file is passed in, override arguments rather than append | +| N/A | `--dry_run` | N/A | performs a dry run to check the validity of the task and flow | +| N/A | `--randomize` | N/A | performs a dry run randomly to check the validity of the task and flow | +| N/A | `--regenerate_expectation`| N/A | regenerates expectation and overrides the expected value only if there's a mismatch | +| N/A | `--generate_expectation` | N/A | generate the expectation and overrides the expectation file | + +## Examples + +The following examples are being performed in the ODIN_II directory: + +### Generating Results for a New Task + +The following commands will generate the results of a new regression test using N processors: + +```bash +make sanitize +``` + +```bash +./verify_odin.sh --generate_expectation -j N -t <regression_test/benchmark/task/<task_name> +``` + +A synthesis_result.json and a simulation_result.json will be generated in the task's folder. +The simulation results for each benchmark are only generated if they syntehsize correctly (no exit error), thus if none of the benchmarks synthesize there will be no simulation_result.json generated. + +### Regenerating Results for a Changed Test + +The following commands will only generate the results of the changes. +If there are new benchmarks it will add to the results. +If there are deleted benchmarks or modified benchmarks the results will be updated accordingly. + +```bash +make sanitize +``` + +```bash +./verify_odin.sh --regenerate_expectation -t <regression_test/benchmark/task/<task_name> +``` + +### Generating Results for a Suite + +The following commands generate the results for all the tasks called upon in a suite. + +```bash +make sanitize +``` + +> **NOTE** +> +> If the suite calls upon the large test **DO NOT** run `make sanitize`. +> Instead run `make build`. + +```bash +./verify_odin.sh --generate_expectation -t <regression_test/benchmark/suite/<suite_name> +``` + +### Checking the configuration file + +The following commands will check if a configuration file is being read properly. + +```bash +make build +``` + +```bash +./verify_odin.sh --dry_run -t <regression_test/benchmark/<path/to/config_file/difrectory> +``` diff --git a/doc/src/odin/index.rst b/doc/src/odin/index.rst index 74326c4871b..6abdf8c4132 100644 --- a/doc/src/odin/index.rst +++ b/doc/src/odin/index.rst @@ -1,522 +1,39 @@ .. _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` +.. toctree:: + :glob: + :maxdepth: 2 + :Caption: Quickstart -************* -INSTALL -************* + quickstart -============= -Prerequisites -============= -1. ctags -2. bison -3. flex -4. gcc 5.x -5. cmake 2.8.12 (minimum version) -6. time -7. cairo +.. toctree:: + :glob: + :maxdepth: 2 + :Caption: User Guide -=========== -Build -=========== + user_guide -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`` +.. toctree:: + :glob: + :maxdepth: 2 + :Caption: verilog Support -.. 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. + verilog_support -.. 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. +.. toctree:: + :glob: + :maxdepth: 2 + :Caption: Developper Guide - - -************* -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. + dev_guide/contributing + dev_guide/regression_test + dev_guide/verify_script + dev_guide/testing diff --git a/doc/src/odin/quickstart.md b/doc/src/odin/quickstart.md new file mode 100644 index 00000000000..93f56439cd7 --- /dev/null +++ b/doc/src/odin/quickstart.md @@ -0,0 +1,67 @@ +# Quickstart + +## Prerequisites + +- ctags +- bison +- flex +- gcc 5.x +- cmake 3.9 (minimum version) +- time +- cairo + +## Building + +To build you may use the Makefile wrapper in the $VTR_ROOT/ODIN_II ``make build`` To build with debug symbols you may use the Makefile wrapper in $VTR_ROOT/ODIN_II ``make debug`` + +> *NOTE* +> +> ODIN uses CMake as it’s build system. CMake provides a portable 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 $VTR_ROOT/ODIN_II ``make test``. +> This will simulate and verify all of the included microbenchmark circuits to ensure that Odin is working correctly on your system. + +## Basic Usage + +./odin_II [arguments] + +*Requires one and only one of `-c`, `-V`, or `-b` + +| arg | following argument | Description | +|------|---|---| +| `-c` | XML Configuration File | an XML configuration file dictating the runtime parameters of odin | +| `-V` | Verilog HDL FIle | You may specify multiple verilog HDL files | +| `-b` | BLIF File | You may specify multiple blif files | +| `-o` | BLIF output file | full output path and file name for the blif output file | +| `-a` | architecture file | You may specify multiple verilog HDL files for synthesis | +| `-h` | | Print help | + +## Example Usage + +The following are simple command-line arguments and a description of what they do. +It is assumed that they are being performed in the Odin_II directory. + +```bash + ./odin_II -V <path/to/verilog/File> +``` + +Passes a verilog HDL file to Odin II where it is synthesized. +Warnings and errors may appear regarding the HDL code. + +```bash + ./odin_II -b <path/to/blif/file> +``` + +Passes a blif file to Odin II where it is synthesized. + +```bash + ./odin_II -V <path/to/verilog/File> -a <path/to/arch/file> -o myModel.blif +``` + +Passes a verilog HDL file and and architecture to Odin II where it is synthesized. +Odin will use the architecture to do technology mapping. +Odin will output the blif in the current directory at `./myModel.blif` +Warnings and errors may appear regarding the HDL code. diff --git a/doc/src/odin/user_guide.md b/doc/src/odin/user_guide.md new file mode 100644 index 00000000000..6c12575bfa0 --- /dev/null +++ b/doc/src/odin/user_guide.md @@ -0,0 +1,206 @@ +# User guide + +## Synthesis Arguments + +| arg | following argument | Description | +|-------|:-----------------------:|------------------------------------------------------- | +| `-c` | XML Configuration File | XML runtime directives for the syntesizer such as the verilog file, and parametrized synthesis | +| `-V` | Verilog HDL FIle | You may specify multiple verilog HDL files for synthesis| +| `-b` | BLIF File | | +| `-o` | BLIF output file | full output path and file name for the blif output file | +| `-a` | architecture file | You may specify multiple verilog HDL files for synthesis | +| `-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 Arguments + +*To activate simulation you must pass one and only one of the following argument:* + +- `-g <number of random vector>` +- `-t <input vector file>` + +Simulation always produces the folowing files: + +- input\_vectors +- output\_vectors +- test.do (ModelSim) + +| arg | following argument | Description | +|--------|:---------------------------:|------------------------------------------------------------------------------------| +| `-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| +| `-t` | Input vector file | Supply a predefined input vector file | +| `-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 seperated list|Comma-separated list of additional pins/nodes to monitor during simulation. (view NOTES) | +| `-U0` | |initial register value to 0 | +| `-U1` | |initial resigster value to 1 | +| `-UX` | |initial resigster value to X (unknown) (DEFAULT) | +| `-L` | Comma seperated 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.) | + +## Examples + +### Example for `-p` + +| argument | explanation | +|-----------------------|:------------------------------------------------------:| +| `-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) + +### Example of .xml configuration file for `-c` + +```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` + +``` bash +## Example vector input file +GLOBAL_SIM_BASE_CLK intput_1 input_2 input_3 clk_input +## Comment +0 0XA 1011 0XD 0 +0 0XB 0011 0XF 1 +0 0XC 1100 0X2 0 +``` + +``` bash +## Example vector output file +output_1 output_2 +## Comment +1011 0Xf +0110 0X4 +1000 0X5 +``` + +> **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 or 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. +> +> The input vector file does not have a clock input, it is assumed it is +> controlled by a single global clock that is why it is necessary to add +> a GLOBAL_SIM_BASE_CLK to the input. To read more about this please +> visit [here](http://www.cs.columbia.edu/~cs6861/sis/blif/index.html). + +### Examples using vector files `-t` and `-T` + +A very useful function of Odin II is to compare the simulated output vector file with the expected output vector file based on an input vector file and a verilog file. +To do this the command line should be: + +```shell +./odin_II -V <Path/to/verilog/file> -t <Path/to/Input/Vector/File> -T <Path/to/Output/Vector/File> +``` + +An error will arrise if the output vector files do not match. + +Without an expected vector output file the command line would be: + +```shell +./odin_II -V <Path/to/verilog/file> -t <Path/to/Input/Vector/File> +``` + +The generated output file can be found in the current directory under the name output_vectors. + +### Example using vector files `-g` + +This function generates N amounnt of random input vectors for Odin II to simulate with. + +```shell +./odin_II -V <Path/to/verilog/file> -g 10 +``` + +This example will produce 10 autogenerated input vectors. These vectors can be found in the current directory under input_vectors and the resulting output vectors can be found under output_vectors. + +## Getting Help + +If you have any questions or concerns there are multiple outlets to express them. +There is a [google group](https://groups.google.com/forum/#!forum/vtr-users) for users who have questions that is checked regularly by Odin II team members. +If you have found a bug please make an issue in the [vtr-verilog-to-routing GitHub repository](https://github.com/verilog-to-routing/vtr-verilog-to-routing/issues?q=is%3Aopen+is%3Aissue+label%3AOdin). + +## Reporting Bugs and Feature Requests + +### Creating an Issue on GitHub + +Odin II is still in development and there may be bugs present. +If Odin II doesn't perform as expected or doesn't adhere to the Verilog Standard, it is important to create a [bug report](https://github.com/verilog-to-routing/vtr-verilog-to-routing/issues/new/choose) in the GitHub repository. +There is a template included, but make sure to include micro-benchmark(s) that reproduces the bug. This micro-benchmark should be as simple as possible. +It is important to link some documentation that provides insight on what Odin II is doing that differs from the Verilog Standard. +Linked below is a pdf of the IEEE Standard of Verilog (2005) that could help. + +[IEEE Standard for Verilog Hardware Description Language](http://staff.ustc.edu.cn/~songch/download/IEEE.1364-2005.pdf) + +If unsure, there are several outlets to ask questions in the [Help](./help.md) section. + +### Feature Requests + +If there are any features that the Odin II system overlooks or would be a great addition, please make a [feature request](https://github.com/verilog-to-routing/vtr-verilog-to-routing/issues/new/choose) in the GitHub repository. There is a template provided and be as in-depth as possible. diff --git a/doc/src/odin/verilog_support.md b/doc/src/odin/verilog_support.md new file mode 100644 index 00000000000..09c700da162 --- /dev/null +++ b/doc/src/odin/verilog_support.md @@ -0,0 +1,186 @@ +# Verilog Support + +## Lexicon + +### Verilog Synthesizable Operators Support + +| Supported Operators|NOT Sup. Operators | +|--------------------|-------------------| +| != | \>\>\> | +| !== | | +| == | | +| === | | +| =\> | | +| \*\* | | +| \^\~ | | +| \<\<\< | | +| \>= | | +| \|\| | | +| \~& | | +| && | | +| \<\< | | +|\<= | | +|\>\> | | +| \~\^ | | +| \~| | | +|-: | | +|+: | | + +### Verilog NON-Synthesizable Operator Support + +| Supported Operators|NOT Sup. Operators| +|--------------------|------------------| +| &&& | | + +### Verilog Synthesizable Keyword Support + +| Supported Keyword | NOT Sup. Keyword | +|-------------------|------------------| +| @() | repeat | +|@\* | deassign | +|always | edge | +|and | forever | +|assign | disable | +|case | | +|defparam | | +|end | | +|endfunction | | +|endmodule | | +|begin | | +|default | | +|else | | +|endcase | | +|endspecify | | +|for | | +|function | | +|if | | +|inout | | +|input | | +|integer | | +|localparam | | +|module | | +|nand | | +|negedge | | +|nor | | +|not | | +|or | | +|output | | +|parameter | | +|posedge | | +|reg | | +|specify | | +|while | | +|wire | | +|xnor | | +|xor | | +|macromodule | | +|generate | | +|genvar | | +|automatic | | +|task | | +|endtask | | +|signed | | + +### Verilog NON-Synthesizable Keyword Support + +|Supported Keyword| NOT Sup. Keyword| +|-----------------|-----------------| +|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 | + +### C Functions support + +| Supported Functions| +|--------------------| +|$clog2 | +|$unsigned | +|$signed | +|$finish | +|$display | + +### Verilog Synthesizable preprocessor Keywords Support + +| Supported Keywords |NOT Sup. Keywords | +|--------------------|-----------------------| +| \`ifdef | \`timescale | +| \`elsif | \`pragma | +| \`ifndef | \`line | +| \`else | \`celldefine | +| \`define | \`endcelldefine | +| \`undef | \`endcelldefine | +| \`endif | \`begin_keywords | +| \`include | \`end_keywords | +| \`default_nettype | \`nounconnected_drive | +| \`resetall | \`unconnected_drive | + +## Syntax + +inline port declaration in the module declaration i.e: + +```verilog +module a(input clk) +... +endmodule +```