cocotb - update documentation

verilog/dv/cocotb/README.md

@@ -12,15 +12,10 @@ 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
-- cocotb 
+- ```docker pull efabless/dv:cocotb```
-```
-  apt update && apt install python3 python3-pip
-  pip3 install cocotb
-  pip3 install cocotb_coverage
-  pip3 install coverage
-  pip3 install cocotb-bus
-```
 - iverilog or vcs 
+- export CARAVEL_ROOT= \<caravel repo root\>
+- export MCW_ROOT= \<caravel_mgmt_soc_litex repo root\>
 
 run a test  
 =============================
@@ -29,48 +24,44 @@ run a test
 
 ```
   -h, --help            show this help message and exit
-  
   -regression REGRESSION, -r REGRESSION
                         name of regression can found in tests.json
-                        
+
   -test TEST [TEST ...], -t TEST [TEST ...]
                         name of test if no --sim provided RTL will be run
                         <takes list as input>
-                        
+
   -sim SIM [SIM ...]    Simulation type to be run RTL,GL&GL_SDF provided only
                         when run -test <takes list as input>
-                        
+
   -testlist TESTLIST, -tl TESTLIST
                         path of testlist to be run
-                        
+
   -tag TAG              provide tag of the run default would be regression
                         name and if no regression is provided would be
                         run_<random float>_<timestamp>_
-                        
+
   -maxerr MAXERR        max number of errors for every test before simulation
                         breaks default = 3
-                        
+
   -vcs, -v              use vcs as compiler if not used iverilog would be used
-  
+
-  -cov, -c              enable code coverage
+  -cov                  enable code coverage
+
+  -corner CORNER [CORNER ...], -c CORNER [CORNER ...]
+                        Corner type in case of GL_SDF run has to be provided
+
+  -keep_pass_unzip      Normally the waves and logs of passed tests would be
+                        zipped. Using this option they wouldn't be zipped
                         
 ```
-
+Refer to [examples](doc/commands_example/README.md) 
 
 Tests 
 ===============
 
-Refer to [tests.json](tests.json) for tests list
+Refer to [tests doc](doc/tests/README.md) for tests list
 
-Directories names fixed for now
-===============
->repo
->>caravel_mgmt_soc_litex/
-
->>caravel
->>>verilog
->>>>dv
->>>>cocotb
 
 cocotb directory tree
 ===============
@@ -90,3 +81,7 @@ cocotb directory tree
 └── wb_models -> contains checkers and models for some caravel blocks 
 
 ```
+
+How to debug
+===============
+` TO BE ADDED`

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

@@ -0,0 +1,22 @@
+# tests commands 
+## run one test in RTL
+``` python3 verify_cocotb.py -t uart_tx -tag uart_tx_rtl ```
+
+``` python3 verify_cocotb.py -t uart_tx -sim RTL -tag uart_tx_rtl ```
+## run one test in GL
+``` python3 verify_cocotb.py -t uart_tx -sim GL -tag uart_tx_gl ```
+## run one test in more than 1 corner
+``` python3 verify_cocotb.py -t uart_tx -sim RTL GL -tag uart_tx_rtl_gl ```
+## run more than 1 test
+``` python3 verify_cocotb.py -t uart_tx uart_rx -tag uart_tx_rx_rtl ```
+
+``` python3 verify_cocotb.py -t uart_tx uart_rx -sim RTL GL -tag uart_tx_rx_rtl_gl ```
+
+# Regressions commands
+## running all RTl tests
+``` python3 verify_cocotb.py -r r_rtl -tag all_rtl ```
+## running all GL tests
+``` python3 verify_cocotb.py -r r_gl -tag all_gl ```
+
+# tests and regression 
+``` python3 verify_cocotb.py -r r_rtl -t uart_tx uart_rx -sim GL -tag all_rtl_and_uart_gl ```

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

@@ -0,0 +1,105 @@
+# gpio
+### gpio_all_i 
+```configure all gpios as mgmt input using automatic approach firmware and check them``` 
+### gpio_all_i_user 
+```configure all gpios as user input using automatic approach firmware and check them``` 
+### gpio_all_i_pu 
+```configure all gpios as mgmt input pull up using automatic approach firmware and check them``` 
+### gpio_all_i_pu_user 
+```configure all gpios as user input pull up using automatic approach firmware and check them``` 
+### gpio_all_i_pd 
+```configure all gpios as mgmt input pull down using automatic approach firmware and check them``` 
+### gpio_all_i_pd_user 
+```configure all gpios as user input pull down using automatic approach firmware and check them``` 
+### gpio_all_bidir_user 
+```configure all gpios as user bidir  using automatic approach firmware and check them``` 
+### gpio_all_o 
+```configure all gpios as mgmt output using automatic approach firmware and check them``` 
+### gpio_all_o_user 
+```configure all gpios as user output using automatic approach firmware and check them``` 
+### mgmt_gpio_out 
+```tests blinking of mgmt gpio bit as an output``` 
+### mgmt_gpio_in 
+```tests blinking of mgmt gpio bit as an output``` 
+### mgmt_gpio_bidir 
+```send random number of blinks through mgmt_gpio and expect to recieve the same number back ``` 
+# housekeeping
+### hk_disable 
+```check Housekeeping SPI disable register is working``` 
+### hk_regs_rst_spi 
+```check reset value of house keeping registers by reading them trough the spi housekeeping``` 
+### hk_regs_wr_wb_cpu 
+```bit bash test for housekeeping registers``` 
+### hk_regs_wr_spi 
+```write then read(the written value) from random housekeeping registers through the SPI housekeeping``` 
+### hk_regs_wr_wb 
+```write then read (the written value) from random housekeeping registers through the firmware but without using CPU, the SPI and system regs can't be read using firmware so the test only GPIO regs inside housekeeping ``` 
+# uart
+### uart_rx 
+```test uart reception``` 
+### uart_loopback 
+```test uart in loopback mode input and output is shorted``` 
+### uart_tx 
+```test uart transmit``` 
+# irq
+### IRQ_timer 
+```test timer0 interrupt``` 
+### IRQ_external 
+```test external interrupt by mprj 7``` 
+### IRQ_uart 
+```test timer0 interrupt``` 
+# bitbang
+### bitbang_cpu_all_i 
+``` configure gpio[0:37] as mgmt input using bitbang and check them``` 
+### bitbang_spi_o 
+```Same as bitbang_cpu_all but configure the gpio using the SPI not the firmware``` 
+### bitbang_spi_i 
+```Same as bitbang_cpu_all_i but configure the gpio using the SPI not the firmware``` 
+### bitbang_cpu_all_o 
+```configure all gpios as mgmt output using bitbang and check them``` 
+### bitbang_cpu_all_01 
+```shift all the register with 01``` 
+### bitbang_cpu_all_10 
+```shift all the register with 10``` 
+### bitbang_cpu_all_1100 
+```shift all the register with 1100``` 
+### bitbang_cpu_all_0011 
+```shift all the register with 0011``` 
+### bitbang_no_cpu_all_o 
+```test disable CPU and control the wishbone to configure gpio[4:37] as mgmt output using bitbang and check them``` 
+### bitbang_no_cpu_all_i 
+```test disable CPU and control the wishbone to configure gpio[0:31] as mgmt input using bitbang and check them``` 
+# timer
+### timer0_oneshot 
+```check timer0 oneshot mode``` 
+### timer0_periodic 
+```check timer0 periodic mode``` 
+# general
+### debug 
+```use caravel in debug mode and check reading and writing from dff2 RAM``` 
+### clock_redirect 
+```check clock redirect is working as expected``` 
+### mem_dff 
+```Memory stress for all space of dff``` 
+### mem_dff2 
+```Memory stress for all space of dff2``` 
+### helloWorld 
+```hello world test``` 
+# housekeeping_spi
+### spi_master_rd 
+```using SPI master for reading from external memory``` 
+### user_pass_thru_rd 
+```use the housekeeping spi in user pass thru mode to read from external mem``` 
+### spi_master_temp 
+```To be deleted``` 
+### spi_rd_wr_nbyte 
+```try housekeeping spi Write and Read in n-byte mode ``` 
+# la
+### la 
+```check logic analyzer input and output enable``` 
+# pll
+### pll 
+```Check pll diffrent configuration``` 
+# cpu
+### cpu_stress 
+```stress the cpu with heavy processing``` 

verilog/dv/cocotb/doc/tests/update_tests.py

@@ -0,0 +1,52 @@
+#!/usr/bin/python3
+import json
+import os
+from fnmatch import fnmatch
+import collections
+
+
+"""This script is for updating the README file with tests from test.json"""
+
+with open('../../tests.json') as f:
+    tests_json = json.load(f)["Tests"]
+
+
+tests = collections.defaultdict(lambda : collections.defaultdict()) #key is testname and value is list of sim types
+for test,test_elements in tests_json.items():
+    if fnmatch(test,"_*"):
+            continue
+    elif fnmatch(test,"*bitbang*"):
+        tests["bitbang"][test] = test_elements["description"]
+    elif fnmatch(test,"*gpio*"):
+        tests["gpio"][test] = test_elements["description"]
+    elif fnmatch(test,"*hk*"):
+        tests["housekeeping"][test] = test_elements["description"]
+    elif fnmatch(test,"*spi*") or fnmatch(test,"*user_pass_thru*"):
+        tests["housekeeping_spi"][test] = test_elements["description"]
+    elif fnmatch(test,"*cpu*"):
+        tests["cpu"][test] = test_elements["description"]
+    elif fnmatch(test,"*irq*") or fnmatch(test,"*IRQ*"):
+        tests["irq"][test] = test_elements["description"]
+    elif fnmatch(test,"*timer*"):
+        tests["timer"][test] = test_elements["description"]
+    elif fnmatch(test,"*spi_master*"):
+        tests["spi_master"][test] = test_elements["description"]
+    elif fnmatch(test,"*uart*"):
+        tests["uart"][test] = test_elements["description"]
+    elif fnmatch(test,"*la*"):
+        tests["la"][test] = test_elements["description"]
+    elif fnmatch(test,"*pll*"):
+        tests["pll"][test] = test_elements["description"]
+    else: 
+        tests["general"][test] = test_elements["description"]
+
+with open("README.md", 'w') as file:
+    for key, value in tests.items():
+        file.write(f"# {key}\n")
+        for test,test_elements in value.items():
+            file.write(f"### {test} \n")
+            file.write(f"```{test_elements}``` \n")
+
+for key, value in tests.items():
+    print(key) 
+    print(value)

verilog/dv/cocotb/tests.json

@@ -183,7 +183,7 @@
             "RTL":["r_rtl","setup","nightly","weekly","tape_out"],
             "GL":["r_gl","nightly","weekly","tape_out"],
             "GL_SDF":["r_sdf","weekly","tape_out"],
-            "description":""}
+            "description":"use caravel in debug mode and check reading and writing from dff2 RAM"}
         ,"spi_master_rd" :{"level":0, 
             "SW":true,
             "RTL":["r_rtl","setup","nightly","weekly","tape_out"],

verilog/dv/cocotb/verify_cocotb.py

@@ -5,7 +5,6 @@ import json
 import sys
 import os
 from pathlib import Path
-import json
 from fnmatch import fnmatch
 from datetime import datetime
 import random