[#72947] add README to SAIF example

examples/saif_example/README.md

@@ -0,0 +1,100 @@
+This example workflow was tested on Debian 12.
+
+## Introduction
+
+To demonstrate the workflow of creating a SAIF file from the simulation trace and a power consumption report generation, we have prepared a simple example located in the `Verilator` project directory under the `examples/saif_example` path.
+
+## Prerequisites
+
+This example assumes that cloned repositories are located in the `~/dev` directory. You will need to clone and build these projects:
+
+- `Verilator` from `https://github.com/antmicro/verilator` on branch `saif`. You can build it with running these commands in the project directory
+
+  ```
+  autoconf
+  ./configure --prefix $(pwd)
+  make -j $(nproc)
+  ```
+
+  and then add the binary directory `~/dev/verilator/bin/` to the `PATH` environmental variable.
+
+- `OpenSTA` from `https://github.com/The-OpenROAD-Project/OpenSTA`. For building instructions, you can refer to the project `README` file. Keep in mind to add the directory where the `sta` binary is located to the `PATH` environmental variable.
+
+- `OpenROAD-flow-scripts` with `Yosys` from `https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts`. To build `Yosys` in `OpenROAD-flow-scripts`, you will need to clone it's submodule with
+
+  `git submodule update --init --recursive tools/yosys`
+
+  then go to the `tools/yosys` directory and run
+
+  `make -j $(nproc) PREFIX=~/dev/OpenROAD-flow-scripts/tools/install/yosys install`
+
+## Workflow
+
+### Generating SAIF file from trace
+From the `examples/saif_example` directory in the `verilator` project, run verilation and compile model to executable with SAIF trace flag enabled `--trace-saif`:
+
+`verilator --cc --exe --build --trace-saif -j -Wno-latch gcd.v saif_trace.cpp`
+
+Then run simulation with the generated binary
+
+`./obj_dir/Vgcd`
+
+This will generate the `simx.saif` file in the current directory with the trace output.
+
+### Generating power consumption report
+For power consumption report generation you will need to prepare simulated model sources for `Yosys` synthesis in the `OpenROAD` project directory. This example workflow uses the `asap7` platform. From the `examples/saif_example` directory in the `verilator` project, copy `saif_trace_example` contents to `OpenROAD-flow-scripts/flow/designs/asap7/` and `src/saif_trace_example` to `OpenROAD-flow-scripts/flow/designs/src/`
+
+```
+cp -r saif_trace_example ~/dev/OpenROAD-flow-scripts/flow/designs/asap7/
+cp -r src/saif_trace_example ~/dev/OpenROAD-flow-scripts/flow/designs/src/
+```
+
+Then go to the `OpenROAD-flow-scripts` project top directory and run the `Yosys` synthesis with
+
+`make -C flow DESIGN_CONFIG=designs/asap7/saif_trace_example/config.mk synth`
+
+Result of the synthesis will be located in the `~/dev/OpenROAD-flow-scripts/flow/results/asap7/saif_trace_example/base/` directory.
+
+Copy previously generated SAIF file from trace to the synthesis result directory with
+
+`cp ~/dev/verilator/examples/saif_example/simx.saif ~/dev/OpenROAD-flow-scripts/flow/results/asap7/saif_trace_example/base/`
+
+For liberty files paths simplicity, you can export the path to their directory as the `LIB_DIR` environmental variable. In this example it will be
+
+```
+export LIB_DIR=~/dev/OpenROAD-flow-scripts/flow/platforms/asap7/lib/NLDM/
+```
+
+Go to the synthesis results directory, run `sta` and then execute commands below
+
+```
+read_liberty $::env(LIB_DIR)/asap7sc7p5t_AO_RVT_FF_nldm_211120.lib.gz
+read_liberty $::env(LIB_DIR)/asap7sc7p5t_INVBUF_RVT_FF_nldm_220122.lib.gz
+read_liberty $::env(LIB_DIR)/asap7sc7p5t_OA_RVT_FF_nldm_211120.lib.gz
+read_liberty $::env(LIB_DIR)/asap7sc7p5t_SIMPLE_RVT_FF_nldm_211120.lib.gz
+read_liberty $::env(LIB_DIR)/asap7sc7p5t_SEQ_RVT_FF_nldm_220123.lib
+
+read_verilog 1_synth.v
+link_design gcd
+
+read_sdc 1_synth.sdc
+
+read_saif -scope gcd simx.saif
+report_power
+```
+
+This will generate power consumption report that should look like this
+
+```
+Group                  Internal  Switching    Leakage      Total
+                          Power      Power      Power      Power (Watts)
+----------------------------------------------------------------
+Sequential             5.19e-05   5.18e-06   5.34e-09   5.71e-05  43.5%
+Combinational          4.15e-05   3.26e-05   2.17e-08   7.42e-05  56.5%
+Clock                  0.00e+00   0.00e+00   0.00e+00   0.00e+00   0.0%
+Macro                  0.00e+00   0.00e+00   0.00e+00   0.00e+00   0.0%
+Pad                    0.00e+00   0.00e+00   0.00e+00   0.00e+00   0.0%
+----------------------------------------------------------------
+Total                  9.35e-05   3.78e-05   2.70e-08   1.31e-04 100.0%
+                          71.2%      28.8%       0.0%
+```