Package: caravel-cocotb
OverviewThis project aims to provide a user friendly environment for adding and running cocotb tests for Caravel user projects.PrerequisitesDocker:Linux||Windows||Mac with Intel Chip||Mac with M1 ChipPython 3.6+ with PIPdocker pull efabless/dv:cocotbClone of CaravelClone of Caravel management repoClone of PDK fromvolareClone of Caravel user projectcaravel_cocotbHow to install caravel_cocotbpipinstallcaravel-cocotbor to install from repogitclonegit@github.com:efabless/caravel-sim-infrastructure.gitgitcheckout<release>cdcaravel-sim-infrastructure/cocotbpipinstall.cd../..caravel_cocotb usagecaravel_cocotb provides a flow and APIs to run simulation on user_project after integerated with caravel. This is so helpful in detecting any bug in the connection between the user project and Caravel IOs, wishbone interface or logic analyzers. Also since it's easy to add and run tests with this flow it can be used to test the whole user project.Creating a TestRequirementsinstallcocotb_caravelupdate netlist for RTL and GL files at<caravel_user_project>/verilog/includes/with the design netlistupdate thedesign_infofile at<caravel_user_project>/verilog/dv/cocotb/design_info.yamlAdding a testThis section explains the steps needed to create a test.A typical test forCaravelconsists of 2 parts:Python/cocotbcode andCcode.Python/cocotbcode is for communicating withCaravelhardware interface inputs, outputs, clock, reset, and power ports/bins.cocotbhere replaces theverilogcode.Ccode provides firmware code that would be loaded into theCaravelCPU.Tests files has to located under<caravel_user_project>/verilog/dv/cocotb/|dv|├──cocotb|│├──<new_test>|││└──<new_test.py>|││└──<new_test.c>|│└──cocotb_tests.py|│└──design_info.yaml|Note: The name ofCfile must match the name ofcocotbtest functionPython TemplateThe template forpythontest:fromcaravel_cocotb.caravel_interfacesimporttest_configurefromcaravel_cocotb.caravel_interfacesimportreport_testfromcaravel_cocotb.caravel_interfacesimportUARTfromcaravel_cocotb.caravel_interfacesimportSPIimportcocotb@cocotb.test()# decorator to mark the test function as cocotb test@report_test# wrapper for configure test reporting filesasyncdef<test_name>(dut):caravelEnv=awaittest_configure(dut)#configure, start up and reset Caravel######################## add test sequence ######################Commonly used APIs to monitor or drive the hardware can be found inpython_api!Warning:New test python function should be imported into cocotb_tests.pyfrom<new_test>.<new_test>import<new_test>C TemplateThe template for Code test:#include<firmware_apis.h>// include required APIsvoidmain(){//////////////////////add test here//////////////////////return;}Commonly used APIs for firmware can be found inC_apiTest ExamplesRefer to thisdirectoryfor tests example generated for 16-bit counterCreating a TestlistRefer tocreating a testlistfor where and how to create a testrun a testTests can run individually or as a test group usingtestlist. Tests can also run in RTL, GL or SDF sims with 9 different corners.To run use caravel_cocotb in the location that has the design_info.yaml file or pass the path to the design_info.yaml file as a command -design_info:usage:caravel_cocotb[-h][-testTEST[TEST...]][-design_infoDESIGN_INFO][-simSIM[SIM...]][-testlistTESTLIST[TESTLIST...]][-tagTAG][-maxerrMAXERR][-vcs][-cornerCORNER[CORNER...]][-zip_passed][-emailtoEMAILTO[EMAILTO...]][-seedSEED][-no_wave][-sdf_setup][-clkCLK][-lint][-macrosMACROS[MACROS...]][-sim_pathSIM_PATH][-verbosityVERBOSITY][-openframe][-check_commits][-no_docker][-compile]Runcocotbtests

optionalarguments:-h,--helpshowthishelpmessageandexit-testTEST[TEST...],-tTEST[TEST...]nameoftestortests.ifno--simprovidedRTLwillberun<takeslistasinput>-design_infoDESIGN_INFO,-diDESIGN_INFOpathtodesign_info.yamlfile-simSIM[SIM...]SimulationtypeRTL,GL&GL_SDFprovidedonlywhenrun-test<takeslistasinput>-testlistTESTLIST[TESTLIST...],-tlTESTLIST[TESTLIST...]pathoftestlisttoberun-tagTAGprovidetagoftherundefaultwouldberegressionnameandifnoregressionisprovidedwouldberun_<randomfloat>_<timestamp>_-maxerrMAXERRmaxnumberoferrorsforeverytestbeforesimulationbreaksdefault=3-vcs,-vuseVCSascompilerifnotusediverilogwouldbeused-cornerCORNER[CORNER...],-cCORNER[CORNER...]CornertypeincaseofGL_SDFrunhastobeprovided-zip_passedzipthewavesandlogsofpassedtests.bydefaultiftherunhasmorethan7testspasstestsresultswouldbezippedautomatically-emailtoEMAILTO[EMAILTO...],-mailEMAILTO[EMAILTO...]mailstosendresultstowhenresultsfinish-seedSEEDrunwithspecificseed-no_wavedisabledumpingwaves-sdf_setuptargetingsetupviolationsbytakingtheSDFmaximumvalues-clkCLKdefinetheclockperiodinnsdefaultdefinedatdesign_info.yaml-lintgeneratelintlogVCSmustbeused-macrosMACROS[MACROS...]Addadditionalverilogmacrosforthedesign-sim_pathSIM_PATHdirectorywheresimulationresultdirectory"sim"wouldbecreatedifNoneitwouldbecreatedundercocotbfolder-verbosityVERBOSITYverbosityoftheconsoleoutputitcanhaveoneof3valuedebug,normalorquietthedefaultvalueisnormal-openframeuseopenframeforthesimulationratherthancaravel-check_commitsusetocheckifreposareuptodate-no_dockerruniverilogwithoutdocker-compileforcerecompilation-no_gen_defaultsdontrungen_gpio_defaultsscript--versionshowprogram'sversionnumberandexitExampleRun one test in RTLcaravel_cocotb -t <testname> -tag run_one_testRun 2 tests in GLcaravel_cocotb -t <test1> <test2>  -sim GLRun testlistcaravel_cocotb -tl <path to testlist> -tag all_rtlCreating a TestlistTestlist is a file that contains a collection of test names to run together.The syntax is simple asYAMLis used to write the testlist# Testlist Can has only 2 elements Tests or includes# Test element has list of dictionaries of tests to includeTests:-{name:<test1>,sim:RTL}-{name:<test1>,sim:GL}-{name:<test2>,sim:RTL}# include has paths  for other testlist to include in this test list# paths are relative to the location of this yaml fileincludes:-<test4>/<testlist>.yaml-<testlist>.yaml-../<test5>/<testlist>.yamlResultsNew directory namedsimwould be created under<repo root>/cocotb/or to the path passed to-sim_pathand it will have all the results.|sim#  directory get generate when run a test│├──<tag># tag of the run││├──compilation# directory contain all logs and build files related to the RTL compilation│││└──compilation.log# log file has all the commands used to run iverilog and any compilation error or warning││├──<simtype>-<testname># test result directory contain all logs and wave related to the test│││└──firmware.hex# hex file used in running this test│││└──<testname>.log# log file generated from cocotb│││└──firmware.log# log file has all the commands used to compile the C code and any compilation error or warning│││└──waves.vcd# waves can be opened by gtkwave│││└──rerun.py# script to rerun the test││└──command.log# command use for this run││└──repos_info.log# contain information about the repos used to run these tests││└──configs.yaml# contain information about the repos used to run these tests││└──runs.log# contains status of the run fails and passes tests│├──hex_files# directory contain all the generated hex files for the runs││Update design_info.yamlNote: This step is required only if make setup isn't used after cloning <caravel_user_project>After any changemake setup-cocotbcan be used.design_info.yamlare used to reference all the needed repos and paths needed to run the tests:fill  it like the following#yaml file contain general design information that would mostly need to be updated in the first run only#eg CARAVEL_ROOT: "/usr/Desktop/caravel_project/caravel/"#like repo https://github.com/efabless/caravelCARAVEL_ROOT:"/usr/caravel_project/caravel/"#eg MCW_ROOT: "/usr/Desktop/caravel_project/caravel_mgmt_soc_litex/"#like repo https://github.com/efabless/caravel_mgmt_soc_litex# MCW_ROOT: "/home/rady/caravel/swift/swift2"MCW_ROOT:"/usr/caravel_project/caravel_mgmt_soc_litex/"#eg USER_PROJECT_ROOT: "/usr/Desktop/caravel_project/caravel_user_project/"#like repo https://github.com/efabless/caravel_user_projectUSER_PROJECT_ROOT:"/usr/caravel_project/"#eg PDK_ROOT: "/usr/Desktop/caravel_project/pdk/"#exported by volarePDK_ROOT:"/usr/pdk"#eg PDK: "sky130A"PDK:sky130A#PDK: gf180mcuC#clock in nsclk:25# true when caravan are simulated instead of Caravelcaravan:false# optional email address to send the results toemailto:[None]HDL include files formatInclude files from<caravel_user_project>/verilog/includelikeincludes.rtl.caravel_user_project,includes.gl.caravel_user_projectandincludes.sdf.caravel_user_projectare used to reference all the needed repos and paths needed to run the tests:The legacy format to reference files is:support verilog file include-v$(USER_PROJECT_VERILOG)/rtl/user_project_wrapper.vCoctb flow supports this format in addition to other formats:support systemVerilg file include-sv$(USER_PROJECT_VERILOG)/rtl/counter.svsupport wild card use-sv$(USER_PROJECT_VERILOG)/rtl/peripherals/*.svsupport add search path for.vhand.svhfiles-I$(USER_PROJECT_VERILOG)/rtl/peripheralsUnexisted python modulesIf the testbench use python modules that are not installed in the docker image, there are 2 options:use-no_dockeroption to run without docker if you have all the required tools installed.Add requirments file to<caravel_user_project>/verilog/dv/cocotb/requirements.txtrich==12.0.1