Skip to content

Commit b39e968

Browse files
emacdo12jeanlegoemacdo12
authored
Odin: documentation update (#1390)
* Odin: documentation update * Last touches * Adjusting the tables * Update Makefile Co-authored-by: jeanlego (Jean-Philippe Legault) <[email protected]> Co-authored-by: emacdo12 <[email protected]>
1 parent 44a62c6 commit b39e968

File tree

10 files changed

+1045
-509
lines changed

10 files changed

+1045
-509
lines changed

‎ODIN_II/README.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Odin_II
2+
=======
3+
4+
Odin II is used for logic synthesis and elaboration, converting a subset of the Verilog Hardware Description Language (HDL) into a BLIF netlist.
5+
6+
-----------------
7+
8+
* **[Quick Start](../doc/src/odin/quickstart.md)**
9+
* **[User Guide](../doc/src/odin/user_guide.md)**
10+
* **[Verilog Support](../doc/src/odin/verilog_support.md)**
11+
* **Developper guide**
12+
* [Contributing](../doc/src/odin/dev_guide/contributing)
13+
* [Regression Tests](../doc/src/odin/dev_guide/regression_test)
14+
* [Regression Tool](../doc/src/odin/dev_guide/verify_script)
15+
* [Validating Tests](../doc/src/odin/dev_guide/testing)

‎ODIN_II/README.rst

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎doc/src/odin/dev_guide/contributing.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Contributing
2+
3+
The Odin II team welcomes outside help from anyone interested.
4+
To fix issues or add a new feature submit a PR or WIP PR following the provided guidelines.
5+
6+
## Creating a Pull Request (PR)
7+
8+
**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.
9+
10+
Pull requests are intended to correct bugs and improve Odin's performance.
11+
To create a pull request, clone the vtr-verilog-rooting repository and branch from the master.
12+
Make changes to the branch that improve Odin II and correct the bug.
13+
**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.
14+
An example of a good test case could be the benchmark found in the "Issue" being addressed.
15+
The results of these new tests need to be regenerate. See [regression tests](./regression_tests) for further instruction.
16+
Push these changes to the cloned repository and create the pull request.
17+
Add a description of the changes made and reference the "issue" that it corrects. There is a template provided on GitHub.
18+
19+
### Creating a "Work in progress" (WIP) PR
20+
21+
**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.
22+
23+
A "work in progress" PR is a pull request that isn't complete or ready to be merged.
24+
It is intended to demonstrate that an Issue is being addressed and indicates to other developpers that they don't need to fix it.
25+
Creating a WIP PR is similar to a regular PR with a few adjustements.
26+
First, clone the vtr-verilog-rooting repository and branch from the master.
27+
Make changes to that branch.
28+
Then, create a pull request with that branch and **include WIP in the title.**
29+
This will automatically indicate that this PR is not ready to be merged.
30+
Continue to work on the branch, pushing the commits regularly.
31+
Like a PR, test cases are also needed to be included through the use of benchmarks.
32+
See [regression tests](./regression_tests) for further instruction.
33+
34+
### Formating
35+
36+
Odin II shares the same contributing philosophy as [VPR](https://docs.verilogtorouting.org/en/latest/dev/contributing/contributing/).
37+
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/regression_test.md

Lines changed: 388 additions & 0 deletions
Large diffs are not rendered by default.

‎doc/src/odin/dev_guide/testing.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# TESTING ODIN II
2+
3+
The verify_odin.sh script will simulate the microbenchmarks and a larger set of benchmark circuits.
4+
These scripts use simulation results which have been verified against ModelSim.
5+
6+
After you build Odin II, run 'make test' to ensure that everything is working correctly on your system.
7+
Unlike the verify\_regression\_tests.sh script, verify\_odin.sh also simulates the
8+
blif output, as well as simulating the verilog with and without the
9+
architecture file.
10+
11+
Before checking in any changes to Odin II, please run both of these scripts to ensure that both of these scripts execute correctly.
12+
If there is a failure, use ModelSim to verify that the failure is within Odin II and not a faulty regression test.
13+
If it is a faulty regression test, make an [issue on GitHub](./reporting_bugs.md).
14+
The Odin II simulator will produce a test.do file containing clock and input vector information for ModelSim.
15+
16+
When additional circuits are found to agree with ModelSim, they should be added to the regression tests.
17+
When new features are added to Odin II, new microbenchmarks should be developed which test those features for regression.
18+
This process is illustrated in the Developper Guide, in the Regression Tests section.
19+
20+
## USING MODELSIM TO TEST ODIN II
21+
22+
ModelSim may be installed as part of the Quartus II Web Edition IDE.
23+
Load the Verilog circuit into a new project in ModelSim.
24+
Compile the circuit, and load the resulting library for simulation.
25+
26+
You may use random vectors via the -g option, or specify your own input vectors using the -t option.
27+
When simulation is complete, load the resulting test.do file into your ModelSim project and execute it.
28+
You may now directly compare the vectors in the output\_vectors file with those produced by ModelSim.
29+
30+
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.
31+
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

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Verify Script
2+
3+
The verify_odin.sh script is designed for generating regression test results.
4+
5+
./verify_odin.sh [args]
6+
7+
## Arguments
8+
9+
*The tool requires a task to run hence `-t <task directory>` must be passed in
10+
11+
| arg | equivalent form | Following argument | Description |
12+
|-------|---------------------------|-------------------------------------|------------------------------------------------------------------------------------------------|
13+
| `-t` | path to directory containing a test |The test types are a task.conf,task_list.conf or a predefined test |
14+
| `-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 |
15+
| `-d` | `--output_dir` | path to directory | This allows the user to change the directory of the run output |
16+
| `-C` | `--config` | path to configuration file | This directs the compiler to a configuration file to append the configuration file of the test|
17+
| `-t` | `--test` | path to directory containing a test | The test types are a task.conf,task_list.conf or a predefined test |
18+
| `-h` | `--help` | N/A | Prints all possible commands and directives |
19+
| `-g` | `--generate_bench` | N/A | Generates input and output vectors for test |
20+
| `-o` | `--generate_output` | N/A | Generates output vector for test given its input vector |
21+
| `-b` | `--build_config` | path to directory | Generates a configuration file for a given directory |
22+
| `-c` | `--clean` | N/A | Clean temporary directory |
23+
| `-f` | `--force_simulate` | N/A | Force the simulation to be executed regardless of the configuration file |
24+
| N/A | `--override` | N/A | if a configuration file is passed in, override arguments rather than append |
25+
| N/A | `--dry_run` | N/A | performs a dry run to check the validity of the task and flow |
26+
| N/A | `--randomize` | N/A | performs a dry run randomly to check the validity of the task and flow |
27+
| N/A | `--regenerate_expectation`| N/A | regenerates expectation and overrides the expected value only if there's a mismatch |
28+
| N/A | `--generate_expectation` | N/A | generate the expectation and overrides the expectation file |
29+
30+
## Examples
31+
32+
The following examples are being performed in the ODIN_II directory:
33+
34+
### Generating Results for a New Task
35+
36+
The following commands will generate the results of a new regression test using N processors:
37+
38+
```bash
39+
make sanitize
40+
```
41+
42+
```bash
43+
./verify_odin.sh --generate_expectation -j N -t <regression_test/benchmark/task/<task_name>
44+
```
45+
46+
A synthesis_result.json and a simulation_result.json will be generated in the task's folder.
47+
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.
48+
49+
### Regenerating Results for a Changed Test
50+
51+
The following commands will only generate the results of the changes.
52+
If there are new benchmarks it will add to the results.
53+
If there are deleted benchmarks or modified benchmarks the results will be updated accordingly.
54+
55+
```bash
56+
make sanitize
57+
```
58+
59+
```bash
60+
./verify_odin.sh --regenerate_expectation -t <regression_test/benchmark/task/<task_name>
61+
```
62+
63+
### Generating Results for a Suite
64+
65+
The following commands generate the results for all the tasks called upon in a suite.
66+
67+
```bash
68+
make sanitize
69+
```
70+
71+
> **NOTE**
72+
>
73+
> If the suite calls upon the large test **DO NOT** run `make sanitize`.
74+
> Instead run `make build`.
75+
76+
```bash
77+
./verify_odin.sh --generate_expectation -t <regression_test/benchmark/suite/<suite_name>
78+
```
79+
80+
### Checking the configuration file
81+
82+
The following commands will check if a configuration file is being read properly.
83+
84+
```bash
85+
make build
86+
```
87+
88+
```bash
89+
./verify_odin.sh --dry_run -t <regression_test/benchmark/<path/to/config_file/difrectory>
90+
```

0 commit comments

Comments
 (0)