DV: Document environment setup

verilog/dv/cocotb/README.md

@@ -1,14 +1,15 @@
 Overview
 ========
-Cocotb environment (CTN) is a dynamic simulation testing environment. It's purpose is to speed testing simulation time and get coverage data. The environment is developed using cocotb, an open source coroutine-based co simulation testbench environment for verifying VHDL and SystemVerilog RTL using Python. CTN has 2 main layers: tests and  whitebox models. Tests layer contain multiple tests and sequences that can communicate with the caravel (dut)  through drivers shown in read at fig 1. Whitebox models layer contain multiple models that should mimic the behavior of each main block inside caravel see fig1. Model is supposed to check if the model is working as expected, if its registers contain the expected values all the time and report coverage of features provided by this block if it’s tested or not. 
+
+Cocotb environment (CTN) is a dynamic simulation testing environment. Its purpose is to speed testing simulation time and get coverage data. The environment is developed using cocotb, an open source coroutine-based co simulation testbench environment for verifying VHDL and SystemVerilog RTL using Python. CTN has 2 main layers: tests and  whitebox models. Tests layer contain multiple tests and sequences that can communicate with the caravel (dut)  through drivers shown in read at fig 1. Whitebox models layer contain multiple models that should mimic the behavior of each main block inside caravel see fig1. Model is supposed to check if the model is working as expected, if its registers contain the expected values all the time and report coverage of features provided by this block if it’s tested or not. 
 
 
  <img src="doc/CTN.png" alt="Alt text" title="fig1. caravel testbench environment (read lines are drivers )">
 
 fig1. caravel testbench environment (read lines are drivers )
 
 Prerequisites
-=============================
+=============
 
 - Docker: [Linux](https://hub.docker.com/search?q=&type=edition&offering=community&operating_system=linux&utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header) ||  [Windows](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header) || [Mac with Intel Chip](https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header) || [Mac with M1 Chip](https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header)
 - Python 3.6+ with PIP
@@ -19,10 +20,12 @@ Prerequisites
 - export PDK_ROOT= \<PDK repo root\>
 - export PDK= \<PDK variant sky130A,sky130B,.... \>
 
+Refer to the [environment setup guide](doc/commands_example/README.md) for more information on how to set up the Caravel environment.
+
 run a test  
-=============================
+==========
 
- Use script verify_cocotb.py
+Usage of the `verify_cocotb.py` scipt:
 
 ```
   -h, --help            show this help message and exit
@@ -59,14 +62,14 @@ run a test
 ```
 Refer to [examples](doc/commands_example/README.md) 
 
-Tests 
-===============
-
-Refer to [tests doc](doc/tests/README.md) for tests list
+Tests
+=====
 
+Refer to the [tests doc](doc/tests/README.md) for a list of tests.
 
 cocotb directory tree
-===============
+=====================
+
 ```
 ├── caravel.py -> contains driving and mentoring functions for caravel interface
 ├── caravel_top.sv -> testbench top level 
@@ -85,5 +88,6 @@ cocotb directory tree
 ```
 
 How to debug
-===============
-` TO BE ADDED`
+============
+
+`TO BE ADDED`

verilog/dv/cocotb/doc/environment_setup/README.md

@@ -0,0 +1,31 @@
+# Environment setup
+
+In order to run the verification simulation you need to set up the Caravel environment.
+To do so, clone [Caravel](https://github.com/efabless/caravel) and the [Caravel management SoC](https://github.com/efabless/caravel_mgmt_soc_litex).
+
+```
+mkdir caravel_verification
+cd caravel_verification
+mkdir pdks
+git clone https://github.com/efabless/caravel
+git clone https://github.com/efabless/caravel_mgmt_soc_litex
+```
+
+Once the repositories are cloned, set the following environment variables:
+
+```
+export PDK_ROOT=$(pwd)/pdks
+export MCW_ROOT=$(pwd)/caravel_mgmt_soc_litex
+export CARAVEL_ROOT=$(pwd)/caravel
+export PDK=sky130A #or SKY130B
+```
+
+The next step is installing the PDK.
+This can be done using the Makefile from the Caravel repository:
+
+```
+cd caravel
+make pdk
+```
+
+Once all the above settings are set and the prerequisites in place, you can run the simulations.