Odin: documentation update

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)

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)

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.

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>
+```