### Basic example with add_files Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/templates.html Basic example showing how to add VHDL files to libraries and run a regression. Sets the HDLRegression install path, adds all .vhd files in ./src to library my_dut_lib, adds a testbench file to my_tb_lib, then starts the regression. ```python import sys # User specify HDLRegression install path: sys.path.append('c:/tools/hdlregression/') # Import the HDLRegression module to the Python script: from hdlregression import HDLRegression # Define a HDLRegression item to access the HDLRegression functionality: hr = HDLRegression() # ------------ USER CONFIG START --------------- # Add all .vhd files in the /src directory to library my_dut_lib: hr.add_files("./src/*.vhd", "my_dut_lib") # Add testbech file to library my_tb_lib: hr.add_files("./tb/my_tb.vhd", "my_tb_lib") # ------------ USER CONFIG END --------------- hr.start() ``` -------------------------------- ### start() usage examples Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Example calls to the start() function. The first enables GUI mode and threading, the second sets netlist timing, and the third passes simulation options. ```python hr.start(gui_mode=True, threading=True) hr.start(netlist_timing='-sdfmin') hr.start(sim_options="-t ps -do \"quietly set NumericStdNoWarnings 1\"") ``` -------------------------------- ### start() method examples Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.tex Three example calls to the start() method. The first enables GUI mode and threading. The second sets netlist_timing to "sdfmin". The third passes simulation options that add simulator commands, here setting the quiet mode and disabling NumericStdNoWarnings. ```python nhro.nstartp(nguimodeo=k+kcTruep, nthreadingo=k+kcTruep) ``` ```python nhro.nstartp(nnetlisttimingo=l+s+s1l+s+s1sdfminl+s+s1p) ``` ```python nhro.nstartp(nsimoptionso=l+s+s2l+s+s2t ps do l+s+sel+s+s2quietly set NumericStdNoWarnings 1l+s+sel+s+s2p) ``` -------------------------------- ### Basic HDLRegression example with add_files Source: https://github.com/hdlutils/hdlregression/blob/main/doc/hdlregression.pdf Basic example showing how to add design and testbench files to specific libraries using hr.add_files() and then start the regression. The sys.path.append line sets the HDLRegression install path. ```python import sys # User specify HDLRegression install path: sys.path.append('c:/tools/hdlregression/') # Import the HDLRegression module to the Python script: from hdlregression import HDLRegression # Define a HDLRegression item to access the HDLRegression functionality: hr = HDLRegression() #------------USER CONFIG START--------------- # Add all.vhd files in the /src directory to library my_dut_lib: hr.add_files("./src/*.vhd", "my_dut_lib") # Add testbech file to library my_tb_lib: hr.add_files("./tb/my_tb.vhd", "my_tb_lib") #------------USER CONFIG END--------------- hr.start() ``` -------------------------------- ### start() Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/api.html Documentation for the start() method of the HDLRegression API, including parameters, examples, and default options tables. ```APIDOC ## start() ### Description Starts the HDLRegression regression test run. The default operation is to run in regression mode without GUI, but this can be changed using the available arguments. ### Method start() ### Parameters - **gui_mode** (boolean) - Optional - Default: False - GUI mode control - **regression_mode** (boolean) - Optional - Default: True - Regression mode control - **stop_on_failure** (boolean) - Optional - Default: False - Stop on first failure - **threading** (boolean) - Optional - Default: False - Enable threading - **com_options** (string/list of string) - Optional - Default: See Table 1 - Compilation options - **sim_options** (string/list of string) - Optional - Default: See Table 2 - Simulation options - **runtime_options** (list of string) - Optional - Default: See Table 3 - Runtime options - **global_options** (list of string) - Optional - Default: See Table 4 - Global options - **elab_options** (list of string) - Optional - Default: See Table 5 - Elaboration options - **netlist_timing** (string) - Optional - Default: None - Netlist timing settings - **keep_code_coverage** (boolean) - Optional - Default: False - Keep code coverage data - **no_default_com_options** (boolean) - Optional - Default: False - Disable default options - **ignore_simulator_exit_codes** (list of int) - Optional - Default: [] - Ignore specific exit codes ### Request Example ```python hr.start(gui_mode=True, threading=True) hr.start(netlist_timing='-sdfmin') hr.start(sim_options="-t ps -do \"quietly set NumericStdNoWarnings 1\"") ``` ### Notes - `gui_mode` selects if simulations should be run from terminal or inside GUI - if supported by the simulator. - `regression_mode` selects run method, i.e. only run tests that have not previously been run, have not passed, or are affected by file changes and need to be rerun. - `stop_on_failure` selects if the regression run shall continue running if a test fails. - `threading` selects if tasks are run in parallel. - `sim_options` adds extra commands to simulator executor call. - `netlist_timing` is a string that has to be set to "-sdfmin", "-sdftyp" or "-sdfmax". - `keep_code_coverage` will keep code coverage results from a previous test run. - `no_default_com_options` disables preconfigured settings for disabling specific warnings. ### Default Options Tables #### Table 1: Compilation Options | Simulator | Default | | --- | --- | | ModelSim (VHDL) | ["-suppress", "1346,1236,1090", "-2008"] | | ModelSim (Verilog) | ["-vlog01compat"] | | NVC | ["--relaxed"] | | GHDL | ["--std=08", "--ieee=standard", "--frelaxed-rules", "--warn-no-shared", "--warn-no-hide"] | | Riviera Pro | ["-2008", "-nowarn", "COMP96_0564", "-nowarn", "COMP96_0048", "-nowarn", "DAGGEN_0001"] | | Vivado | ["--2008"] | #### Table 2: Simulation Options | Simulator | Default | | --- | --- | | ModelSim | [] | | NVC | [] | | GHDL | [] | | Riviera Pro | [] | | Vivado | [] | #### Table 3: Runtime Options | Simulator | Default | | --- | --- | | Modelsim | [] | | NVC | [] | | GHDL | [] | | Riviera Pro | [] | | Vivado | [] | #### Table 4: Global Options | Simulator | Default | | --- | --- | | Modelsim | [] | | NVC | ["--stderr=error", "--messages=compact", "-M64m", "-H64m"] | | GHDL | [] | | Riviera Pro | [] | | Vivado | [] | #### Table 5: Elaboration Options | Simulator | Default | | --- | --- | | Modelsim | [] | | NVC | ["-e", "--no-save", "--jit"] | | GHDL | [] | | Riviera Pro | [] | | Vivado | [] | ``` -------------------------------- ### Basic example of using HDLRegression Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.pdf This example shows a basic HDLRegression script. It sets the install path, imports the module, creates an HDLRegression instance, and adds VHDL files from a source directory and a testbench file. The script then starts the regression with hr.start(). ```python import sys # User specify HDLRegression install path: sys.path.append('c:/tools/hdlregression/') # Import the HDLRegression module to the Python script: from hdlregression import HDLRegression # Define a HDLRegression item to access the HDLRegression functionality: hr = HDLRegression() #------------USER CONFIG START--------------- # Add all.vhd files in the /src directory to library my_dut_lib: hr.add_files("./src/*.vhd", "my_dut_lib") # Add testbech file to library my_tb_lib: hr.add_files("./tb/my_tb.vhd", "my_tb_lib") #------------USER CONFIG END--------------- hr.start() ``` -------------------------------- ### set_simulator_wave_file_format example with start Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Example of setting the wave file format to VCD and starting HDLRegression in GUI mode. GUI mode is required for wave dumping. ```python hr.set_simulator_wave_file_format("VCD") hr.start(gui_mode=True) ``` -------------------------------- ### Advanced HDLRegression example with generics and CSV report Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/templates.html Advanced example showing a complete HDLRegression setup: adds VHDL source and testbench files, generates a list of generic combinations using itertools.product, adds generics for a testbench, specifies a CSV report, and starts in regression mode. Requires a user-specified HDLRegression install path via sys.path.append. ```python from itertools import product from hdlregression import HDLRegression import sys # User specify HDLRegression install path: sys.path.append('c:/tools/hdlregression/') # Import the HDLRegression module to the Python script: # Import other Python package(s): # Define a HDLRegression item to access the HDLRegression functionality: hr = HDLRegression() # ------------ USER CONFIG START --------------- # Add Python functions here if needed: # Return a list with the product of the generics def create_generics(bus_width, master_mode, input_file, output_file): generics = [] for bus_width, master_mode, input_file, output_file in product(bus_width, master_mode, input_file, output_file): generics.append(["GC_BUS_WIDTH",bus_width, "GC_MASTER_MODE",master_mode, "GC_INPUT_FILE",input_file, "GC_OUTPUT_FILE",output_file]) return generics # Add all source files to library my_dut_lib: hr.add_files("./src/*.vhd", "my_dut_lib") # Add all testbench related files to library my_tb_lib: hr.set_library("my_tb_lib") hr.add_files("./tb/my_dut_tb.vhd") hr.add_files("./tb/my_dut_th.vhd") hr.add_files("./tb/my_dut_if_stuck_tb.vhd") hr.add_files("./tb/my_dut_pin_pulse_tb.vhd") # Get a list with the product of selected generics: generics = create_generics(bus_width=[2, 4, 8, 16], master_mode=[ True, False], input_file="in_data.txt", output_file="out_data.txt") # Add generics for testbench run: hr.add_generics(entity="my_dut_tb", generics=generics) # Specify output report as CSV: hr.gen_report(report_file="project_report.csv") # ------------ USER CONFIG END --------------- hr.start(regression_mode=True) ``` -------------------------------- ### start() Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.tex Starts the regression run after configuration is complete. ```APIDOC ## start() ### Description Starts the regression run. This method should be called after all configuration and file additions are complete. ### Method Method ### Endpoint hr.start() ### Parameters No parameters. ### Request Example ```python hr.start() ``` ### Response #### Success Response No return value. ``` -------------------------------- ### Basic HDLRegression template Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/templates.html Basic template for getting started with HDLRegression. Uncomment and set the sys.path line if HDLRegression is not installed as a Python package. Add files using hr.add_files() with optional library name, then call hr.start(). ```python import sys # ----------- USER HDLRegression PATH ----------------- # If HDLRegression is not installed as a Python package (see doc) # then uncomment the following line and set the path for # the HDLRegression install folder : #sys.path.append() # Import the HDLRegression module to the Python script: from hdlregression import HDLRegression # Define a HDLRegression item to access the HDLRegression functionality: hr = HDLRegression() # ------------ USER CONFIG START --------------- # => hr.add_files() # Use default library my_work_lib # => hr.add_files(, ) # or specify a library name. # ------------ USER CONFIG END --------------- hr.start() ``` -------------------------------- ### Start simulation with GUI and threading Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.pdf Starts the regression with GUI mode and threading enabled. After calling start(), adding files or changing simulation configurations is not permitted. ```python hr.start(gui_mode=True, threading=True) ``` -------------------------------- ### Advanced HDLRegression example with generics product Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.tex Advanced example that generates a product of generics using itertools.product and runs a regression. It adds source and testbench files to libraries, adds the generated generics to the testbench, specifies a CSV report, and starts in regression mode. ```python from itertools import product from hdlregression import HDLRegression import sys # User specify HDLRegression install path: sys.path.append("c:/tools/hdlregression/") # Import the HDLRegression module to the Python script: # Import other Python package(s): # Define a HDLRegression item to access the HDLRegression functionality: hr = HDLRegression() # USER CONFIG START # Add Python functions here if needed: # Return a list with the product of the generics def creategenerics(buswidth, mastermode, inputfile, outputfile): generics = [] for buswidth, mastermode, inputfile, outputfile in product(buswidth, mastermode, inputfile, outputfile): generics.append(["GCBUSWIDTH",buswidth, "GCMASTERMODE",mastermode, "GCINPUTFILE",inputfile, "GCOUTPUTFILE",outputfile]) return generics # Add all source files to library mydutlib: hr.addfiles("./src/*.vhd", "mydutlib") # Add all testbench related files to library mytblib: hr.setlibrary("mytblib") hr.addfiles("./tb/myduttb.vhd") hr.addfiles("./tb/mydutth.vhd") hr.addfiles("./tb/mydutifstucktb.vhd") hr.addfiles("./tb/mydutpinpulsetb.vhd") # Get a list with the product of selected generics: generics = creategenerics(buswidth=[2, 4, 8, 16], mastermode=[ True, False], inputfile="indata.txt", outputfile="outdata.txt") # Add generics for testbench run: hr.addgenerics(entity="myduttb", generics=generics) # Specify output report as CSV: hr.genreport(reportfile="projectreport.csv") # USER CONFIG END hr.start(regressionmode=True) ``` -------------------------------- ### Install HDLRegression with setup.py Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/intro.html Build and install HDLRegression as a Python package using the setup.py script. Run these commands in the HDLRegression root folder. ```bash python3 setup.py build ``` ```bash python3 setup.py develop ``` -------------------------------- ### RTL and Netlist script example Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.pdf A Python script template that defines run_rtl() and run_netlist() functions, each creating an HDLRegression instance, adding files (user configuration), and calling start(). The main() function selects between 'rtl' and 'netlist' based on command-line arguments. ```python import sys #-----------USER HDLRegression PATH----------------- # If HDLRegression is not installed as a Python package (see doc) # then uncomment the following line and set the path for # the HDLRegression install folder : #sys.path.append() # Import the HDLRegression module to the Python script: from hdlregression import HDLRegression def run_rtl(): ''' Setup test environment for RTL simulations. ''' # Define a HDLRegression item to access the HDLRegression functionality: hr = HDLRegression() #------------USER CONFIG START--------------- # => hr.add_files() # Use default library my_work_lib # => hr.add_files(, ) # or specify a library name. #------------USER CONFIG END--------------- hr.start() def run_netlist(): ''' Setup test environment for Netlist simulations. ''' # Define a HDLRegression item to access the HDLRegression functionality: hr = HDLRegression() #------------USER CONFIG START--------------- # => hr.add_files() # Use default library my_work_lib # => hr.add_files(, ) # or specify a library name. #------------USER CONFIG END--------------- hr.start() def main(): ''' Main method, selecting RTL or Netlist simulations. ''' args = sys.argv[1:] if len(args) > 0: selection = args[0].lower() sys.argv.remove(selection) if 'rtl' == selection: run_rtl() elif 'netlist' == selection: run_netlist() else: print('Please select "rtl" or "netlist" run.') else: print('Please select "rtl" or "netlist" run.') if __name__ == "__main__": main() ``` -------------------------------- ### start() Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/api.html Starts the regression test run. This is a basic method to execute the configured tests. ```APIDOC ## start() ### Description Starts the regression test run. This is a basic method to execute the configured tests. ### Method start ### Parameters Not specified in the source. ``` -------------------------------- ### add_testcase() usage examples Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Example calls to add_testcase() showing supported selector forms. Wildcards (*, ?, [seq], [!seq]) can be used. Library filtering is only supported via add_testcase() and CLI. The start() method returns error code 1 if no test cases matched. ```python add_testcase("interface_tb.test_arch.read_test") add_testcase("interface_tb..read_") add_testcase("lib_uart:interface_tb.func.*") add_testcase(":interface_tb.") add_testcase(testcase_list) ``` -------------------------------- ### configure_library() example Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/_sources/api.rst.txt Example call to configure_library() that sets never_recompile to True for the 'can_ip_library' library. ```python hr.configure_library(library='can_ip_library', never_recompile=True) ``` -------------------------------- ### start() Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/api.html Initiates compilation, simulation, and reporting. After calling this method, adding files or making changes to simulation configurations is not permitted. ```APIDOC ## start() ### Description Initiates compilation, simulation, reporting, etc. After calling this method, adding files or making changes to simulation configurations in the regression script is not permitted. ### Method start ### Return Code The return code from the start() method is either 0 or 1, based on the success criteria: | Criteria | Return code | | --- | --- | | No compilation error and test case(s) has been run without errors | 0 | | No compilation error and no test case run | 1 | | No compilation error and test case run with one or more errors | 1 | | Compilation error (no test cases will be run) | 1 | ``` -------------------------------- ### start() Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/_sources/api.rst.txt Starts the HDL regression run with the specified configuration options. Parameters control GUI mode, threading, compilation and simulation options, and other runtime behaviors. ```APIDOC ## start() ### Description Starts the HDL regression run with the specified configuration options. Parameters control GUI mode, threading, compilation and simulation options, and other runtime behaviors. ### Method start() ### Parameters - **gui_mode** (boolean) - Default: False - GUI mode control - **regression_mode** (boolean) - Default: True - Regression mode control - **stop_on_failure** (boolean) - Default: False - Stop on first failure - **threading** (boolean) - Default: False - Enable threading - **com_options** (string/list of string) - Default: See table 1 - Compilation options - **sim_options** (string/list of string) - Default: See table 2 - Simulation options - **runtime_options** (list of string) - Default: See table 3 - Runtime options - **global_options** (list of string) - Default: See table 4 - Global options - **elab_options** (list of string) - Default: See table 5 - Elaboration options - **netlist_timing** (string) - Default: None - Netlist timing settings - **keep_code_coverage** (boolean) - Default: False - Keep code coverage data - **no_default_com_options** (boolean) - Default: False - Disable default options - **ignore_simulator_exit_codes** (list of int) - Default: [] - Ignore specific exit codes ### Request Example ```python hr.start(gui_mode=True, threading=True) hr.start(netlist_timing='-sdfmin') hr.start(sim_options="-t ps -do \"quietly set NumericStdNoWarnings 1\"") ``` ### Response No return value documented. ``` -------------------------------- ### set_simulator examples for GHDL and ModelSim Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Example of setting the simulator to GHDL with default options and to ModelSim with a custom executable path. The path uses forward slashes as required. ```python hr.set_simulator(simulator="GHDL") hr.set_simulator(simulator="MODELSIM", path='c:/tools/intelFPGA/20.1/modelsim_ase/win32aloem') ``` -------------------------------- ### set_library() example Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Example call to set_library() that sets the default library to "testbench_lib". ```python hr.set_library("testbench_lib") ``` -------------------------------- ### start() Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Initiates compilation, simulation, reporting, etc. After calling this method, no further changes to files or configurations are permitted. ```APIDOC ## start() ### Description Initiates compilation, simulation, reporting, etc. After calling this method, adding files or making changes to simulation configurations in the regression script is not permitted. ### Method N/A (Python method) ### Endpoint N/A (Python method) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```python hr.start() ``` ### Response #### Success Response (200) - **return_code** (integer) - 0 or 1, based on whether the success criteria are met. #### Response Example ```python return_code = hr.start() ``` ### Notes - Ensure all necessary files and configurations are set before invoking this method. ``` -------------------------------- ### start(gui_mode, stop_on_failure, regression_mode, threading, sim_options, netlist_timing, com_options) Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.pdf Starts the regression run, including compilation, simulation, and reporting. Returns 0 or 1 based on success criteria. ```APIDOC ## start(gui_mode, stop_on_failure, regression_mode, threading, sim_options, netlist_timing, com_options) ### Description Initiates compilation, simulation, and reporting. After calling this method, adding files or changing simulation configurations is not permitted. ### Method start ### Parameters - **gui_mode** (boolean) - Optional - Default: False - GUI mode control. - **regression_mode** (boolean) - Optional - Default: True - Regression mode control. - **stop_on_failure** (boolean) - Optional - Default: False - Stop on first failure. - **threading** (boolean) - Optional - Default: False - Enable threading. - **com_options** (string/list of string) - Optional - Compilation options. - **sim_options** (string/list of string) - Optional - Simulation options. - **runtime_options** (list of string) - Optional - Runtime options. - **global_options** (list of string) - Optional - Global options. - **elab_options** (list of string) - Optional - Elaboration options. - **netlist_timing** (string) - Optional - Netlist timing settings. - **keep_code_coverage** (boolean) - Optional - Default: False - Keep code coverage data. - **no_default_com_options** (boolean) - Optional - Default: False - Disable default options. - **ignore_simulator_exit_codes** (list of int) - Optional - Default: [] - Ignore specific exit codes. ### Return Code - 0: No compilation error and test case(s) run without errors. - 1: No compilation error and no test case run, or test case run with errors, or compilation error. ### Example hr.start(gui_mode=True, threading=True) hr.start(netlist_timing='-sdfmin') ``` -------------------------------- ### hr.start() Source: https://github.com/hdlutils/hdlregression/blob/main/doc/hdlregression.pdf Starts the HDLRegression environment with optional simulation options. ```APIDOC ## [START] hr.start() ### Description Starts the HDLRegression environment with optional simulation options. ### Method START ### Endpoint hr.start() ### Parameters #### Query Parameters - **sim_options** (string) - Optional - Extra command-line options to pass to the simulator. ### Request Example ```python hr.start(sim_options="-t ps -do\"quietly set NumericStdNoWarnings 1\"") ``` ### Response #### Success Response (200) - **status** (string) - "success" #### Response Example ```json { "status": "success" } ``` ``` -------------------------------- ### Install HDLRegression package (develop) Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/_sources/intro.rst.txt Installs HDLRegression in development mode using setup.py. This makes the package importable without adding to PATH. ```console python3 setup.py develop ``` -------------------------------- ### get_results() Tuple Unpacking Example Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Alternative example of using get_results() with tuple unpacking to assign the three result lists. ```python (passed_tests, failed_tests, not_run_tests) = hr.get_results() ``` -------------------------------- ### get_results() example Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/api.html Example of calling get_results() and unpacking the returned list into passed_tests, failed_tests, and not_run_tests. ```python result_list = hr.get_results() passed_tests = result_list[0] failed_tests = result_list[1] not_run_tests = result_list[2] ``` ```python (passed_tests, failed_tests, not_run_tests) = hr.get_results() ``` -------------------------------- ### Install HDLRegression as a Python package Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.tex Commands to build and install HDLRegression as a Python package. The first two commands build and install the package in development mode, while the third uses pip to install from the current directory. ```bash python3 setup.py build ``` ```bash python3 setup.py develop ``` ```bash pip install . ``` -------------------------------- ### start() function signature Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Shows the signature of the start() function with its arguments. The default operation is regression mode without GUI enabled, but this can be changed using the available arguments or command line interfaces. ```python start(, , , , , , ) ``` -------------------------------- ### get_num_tests_run() Example Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Example of using get_num_tests_run() to store the number of tests run. ```python num_tests = hr.get_num_tests_run() ``` -------------------------------- ### Start regression with sim_options Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.pdf Starts the regression run with extra simulator options. The sim_options string is passed to the simulator executor call. ```python hr.start(sim_options="-t ps -do\"quietly set NumericStdNoWarnings 1\"") ``` -------------------------------- ### Start simulation with netlist timing Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.pdf Starts the regression with netlist timing options. The netlist_timing argument is used for back-annotated timing files. ```python hr.start(netlist_timing='-sdfmin') ``` -------------------------------- ### get_results() Example Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Example of using get_results() to retrieve the list of test results and assign each category to a variable. ```python result_list = hr.get_results() passed_tests = result_list[0] failed_tests = result_list[1] not_run_tests = result_list[2] ``` -------------------------------- ### add_files() examples Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.pdf Examples of using the add_files() method to specify files with optional library name, hdl_version, netlist_inst, and code_coverage arguments. The library name defaults to 'my_work_lib' and hdl_version defaults to 2008. ```python hr.add_files("../src/my_testbench.vhd", "my_testbench_lib", hdl_version='2008') ``` ```python hr.add_files("../backend/my_design.sdf", "my_design_lib", hdl_version='2008', netlist_inst='/my_testnech/i_test_harness/i_dut') ``` ```python hr.add_files("../src/*.vhd", code_coverage=True) ``` -------------------------------- ### add_file_to_run_folder() usage examples Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Example calls to add_file_to_run_folder(). Relative paths are resolved relative to the regression script, not the current working directory. ```python 1. hr.add_file_to_run_folder(filename="c:/design/tb/input_data.txt", tc_id="1") 2. hr.add_file_to_run_folder(filename="../tb/input_data.txt", tc_id="7") ``` -------------------------------- ### start() Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Runs regression tests in either regression or GUI mode. Returns a status code indicating the outcome of the compilation and test execution. ```APIDOC ## start() ### Description Runs regression tests in either regression or GUI mode. Returns a status code indicating the outcome of the compilation and test execution. ### Method N/A (Python function) ### Endpoint N/A (Python function) ### Parameters #### Arguments - **gui_mode** (boolean) - Optional - GUI mode control. Default: False - **regression_mode** (boolean) - Optional - Regression mode control. Default: True - **stop_on_failure** (boolean) - Optional - Stop on first failure. Default: False - **threading** (boolean) - Optional - Enable threading. Default: False - **com_options** (string/list of string) - Optional - Compilation options. Default: See Table 1 - **sim_options** (string/list of string) - Optional - Simulation options. Default: See Table 2 - **runtime_options** (list of string) - Optional - Runtime options. Default: See Table 3 - **global_options** (list of string) - Optional - Global options. Default: See Table 4 - **elab_options** (list of string) - Optional - Elaboration options. Default: See Table 5 - **netlist_timing** (string) - Optional - Netlist timing settings. Default: None - **keep_code_coverage** (boolean) - Optional - Keep code coverage data. Default: False - **no_default_com_options** (boolean) - Optional - Disable default options. Default: False - **ignore_simulator_exit_codes** (list of int) - Optional - Ignore specific exit codes. Default: [] ### Request Example ```python hr.start(gui_mode=True, threading=True) hr.start(netlist_timing='-sdfmin') hr.start(sim_options="-t ps -do \"quietly set NumericStdNoWarnings 1\"") ``` ### Response #### Success Response (0) - **return_code** (int) - 0 if no compilation error and test case(s) run without errors. #### Success Response (1) - **return_code** (int) - 1 if any of the following: no compilation error and no test case run, no compilation error and test case run with one or more errors, or compilation error. #### Response Example ``` 0 ``` ### Error Handling - Returns 1 for compilation errors or test failures. ### Tables #### Table 1: Compilation Options | Simulator | Default | |--------------------|-------------------------------------------------------------------------------------------------| | ModelSim (VHDL) | ["-suppress", "1346,1236,1090", "-2008"] | | ModelSim (Verilog) | ["-vlog01compat"] | | NVC | ["–relaxed"] | | GHDL | ["–std=08", "–ieee=standard", "–frelaxed-rules", "–warn-no-shared", "–warn-no-hide"] | | Riviera Pro | ["-2008", "-nowarn", "COMP96_0564", "-nowarn", "COMP96_0048", "-nowarn", "DAGGEN_0001"] | | Vivado | ["–2008"] | #### Table 2: Simulation Options | Simulator | Default | |-------------|-----------| | ModelSim | [] | | NVC | [] | | GHDL | [] | | Riviera Pro | [] | | Vivado | [] | #### Table 3: Runtime Options | Simulator | Default | |-------------|-----------| | Modelsim | [] | | NVC | [] | | GHDL | [] | | Riviera Pro | [] | | Vivado | [] | #### Table 4: Global Options | Simulator | Default | |-------------|----------------------------------------------------------| | Modelsim | [] | | NVC | ["–stderr=error", "–messages=compact", "-M64m", "-H64m"] | | GHDL | [] | | Riviera Pro | [] | | Vivado | [] | #### Table 5: Elaboration Options | Simulator | Default | |-------------|-----------| | Modelsim | [] | | NVC | [] | | GHDL | [] | | Riviera Pro | [] | | Vivado | [] | ``` -------------------------------- ### Set a pre-simulation Tcl command with set_pre_sim_tcl_cmd() Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Sets a Tcl command to be executed by the simulator before a test starts, then starts the regression. The command must be set before calling start(). It applies to simulators with a Tcl front-end (e.g., ModelSim/Questa, Riviera-PRO); other simulators may ignore it. Calling this method multiple times overwrites the previous command. ```python hr.set_pre_sim_tcl_cmd('do ../scripts/pre_sim.do') hr.start() ``` -------------------------------- ### Example 1: Creating HDLRegression object Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Example 1: Two ways to create an HDLRegression object. The first uses default auto-detection; the second explicitly selects the GHDL simulator. ```python 1. hr = HDLRegression() 2. hr = HDLRegression(simulator="ghdl") ``` -------------------------------- ### run_command() Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Executes a command at the given stage in the regression script. Pre-simulation commands must be called before start(), and post-simulation commands after start(). ```APIDOC ## run_command() ### Description Executes a command at the given stage in the regression script. Pre-simulation commands must be called before `start()`, and post-simulation commands after `start()`. By default, no output is printed to the terminal unless `verbose` is set to `True`. ### Method N/A (Python method) ### Endpoint N/A (Python method) ### Parameters #### Arguments - **command** (string) - Required - The command to execute. - **verbose** (boolean) - Optional - If `True`, prints command output to the terminal. Default is `False`. ### Request Example ```python hr.run_command('python3 ../script/run_spec_cov.py --config ../script/config.txt') hr.run_command('vsim -version', verbose=True) ``` ### Response No return value. ### Notes - Relative paths are relative to the regression script, not the current working directory. ``` -------------------------------- ### Uninstall HDLRegression (setup.py) Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/_sources/intro.rst.txt Uninstalls HDLRegression when installed via setup.py develop. ```console python3 setup.py develop --uninstall ``` -------------------------------- ### get_args() - Get parsed arguments Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Gets the parsed arguments from HDLRegression. Useful when an argparser object is created in the regression script. See HDLRegression() example 2 for usage. ```python args = hr.get_args() ``` -------------------------------- ### Remove file with hr.remove_file() Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.pdf Removes a file from a library, e.g., after using add_files() with asterisk. The filename cannot include the path or wildcards. The example adds files with a wildcard, removes an unused file, and starts the regression. ```python hr.add_files("../src/*.vhd","testbench_lib") hr.remove_file("unused_file.vhd","testbench_lib") hr.start() ``` -------------------------------- ### Build HDLRegression package Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/_sources/intro.rst.txt Builds the HDLRegression package using setup.py. Run from the HDLRegression root folder. ```console python3 setup.py build ``` -------------------------------- ### add_files() with explicit library names and options Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Example 1: adds a VHDL testbench, an SDF back-annotated timing file (requires netlist_inst), and a wildcard set of VHDL files with code coverage enabled. Relative paths are relative to the regression script, not the current working directory. ```python hr.add_files("../src/my_testbench.vhd", "my_testbench_lib", hdl_version='2008') hr.add_files("../backend/my_design.sdf", "my_design_lib", hdl_version='2008', netlist_inst='/my_testnech/i_test_harness/i_dut') hr.add_files("../src/*.vhd", code_coverage=True) ``` -------------------------------- ### get_num_fail_tests() Example Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Example of using get_num_fail_tests() to store the number of failed tests. ```python num_failed_tests = hr.get_num_fail_tests() ``` -------------------------------- ### get_num_pass_tests() Example Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Example of using get_num_pass_tests() to store the number of passed tests. ```python num_passed_tests = hr.get_num_pass_tests() ``` -------------------------------- ### add_testcase examples Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.pdf Selects test cases to run. Supports wildcards and optional library prefix. If no test cases are added, all discovered tests run. CLI selections override scripted ones. ```python add_testcase("interface_tb.test_arch.read_test") ``` ```python add_testcase("interface_tb..read_") ``` ```python add_testcase("lib_uart:interface_tb.func.*") ``` ```python add_testcase(":interface_tb.") ``` ```python add_testcase(testcase_list) ``` -------------------------------- ### Run pre-processing and simulations in parallel using 10 threads Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/cli.html Runs both pre-processing and test case simulations in parallel with the specified number of threads. Note that running simulations in parallel may require that many simulator licenses. ```bash > python ../test/regression.py -tg receive_tests -t 10 ``` -------------------------------- ### Uninstall HDLRegression Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.tex Commands to uninstall HDLRegression. The first is for a development install, the second for a pip install. ```bash python3 setup.py develop uninstall ``` ```bash pip uninstall hdlregression ``` -------------------------------- ### Install HDLRegression via pip Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/_sources/intro.rst.txt Installs HDLRegression using the Python package-management system pip. ```console pip install . ``` -------------------------------- ### set_testcase_identifier_name example Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/api.html Example call to set the testcase identifier name to "GC_TESTCASE". ```text hr.set_testcase_identifier_name("GC_TESTCASE") ``` -------------------------------- ### get_num_pass_with_minor_alert_tests() Example Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/api.rst Example of using get_num_pass_with_minor_alert_tests() to store the number of passed tests with minor alerts. ```python num_passed_tests_with_minor_alerts = hr.get_num_pass_with_minor_alert_tests() ``` -------------------------------- ### set_result_check_string example Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/api.html Example call to set the result check string to "testcase passed". ```text hr.set_result_check_string("testcase passed") ``` -------------------------------- ### set_simulator_wave_file_format() example Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.tex Sets the wave dump format to VCD and enables GUI mode. VCD is the default if not selected; GUI mode must be enabled via API or CLI. ```python wave_format="VCD" ``` ```python gui_mode=True ``` -------------------------------- ### Add HDLRegression to Python PATH Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/_sources/intro.rst.txt Adds the HDLRegression install path to Python PATH and imports HDLRegression without package installation. ```python import sys sys.path.append() from hdlregression import HDLRegression ``` -------------------------------- ### VHDL testbench example with --hdlregression:tb pragma Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/testbench.html VHDL testbench that HDLRegression discovers via the --hdlregression:tb pragma. Includes a generic GC_TESTCASE to select test cases, UVVM context, and a p_main process that logs messages and ends simulation with report_alert_counters and std.env.stop. ```vhdl library IEEE; use IEEE.std_logic_1164.all; use IEEE.numeric_std.all; library uvvm_util; context uvvm_util.uvvm_util_context; -- Include when using VVC: -- library uvvm_vvc_framework; -- use uvvm_vvc_framework.ti_vvc_framework_support_pkg.all; --hdlregression:tb entity tb_example is generic ( GC_TESTCASE : string := "UVVM" ); end entity tb_example; architecture func of tb_example is constant C_SCOPE : string := C_TB_SCOPE_DEFAULT; constant C_CLK_PERIOD : time := 10 ns; begin ----------------------------------------------------------------------------- -- Instantiate test harness ----------------------------------------------------------------------------- -- i_test_harness : entity work.test_harness; ------------------------------------------------ -- PROCESS: p_main ------------------------------------------------ p_main: process begin ----------------------------------------------------------------------------- -- Wait for UVVM to finish initialization ----------------------------------------------------------------------------- -- await_uvvm_initialization(VOID); ----------------------------------------------------------------------------- -- Set UVVM verbosity level ----------------------------------------------------------------------------- -- enable_log_msg(ALL_MESSAGES); disable_log_msg(ALL_MESSAGES); enable_log_msg(ID_SEQUENCER); enable_log_msg(ID_LOG_HDR); ----------------------------------------------------------------------------- -- Test sequence ----------------------------------------------------------------------------- log(ID_SEQUENCER, "Running testcase: " & GC_TESTCASE, C_SCOPE); if GC_TESTCASE = "check_reset_defaults" then -- reset checks elsif GC_TESTCASE = "test_dut_write" then -- write checks elsif GC_TESTCASE = "test_dut_read" then -- read checks end if; ----------------------------------------------------------------------------- -- Ending the simulation ----------------------------------------------------------------------------- wait for 1000 ns; -- to allow some time for completion report_alert_counters(FINAL); -- Report final counters and print conclusion for simulation (Success/Fail) log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE); -- Finish the simulation std.env.stop; wait; -- to stop completely end process p_main; end func; ``` -------------------------------- ### Run test in GUI mode with GHDL and open VCD in GTKWave Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.pdf For GHDL/NVC, GUI mode creates sim.vcd files in each test case run folder. The example shows running with -g -s ghdl and then opening the VCD file in GTKWave. ```bash python ../test/regression.py -tc uart_vvc_tb.func.check_simple_transmit -g -s ghdl ``` ```bash gtkwave ./hdlregression/test/uart_vvc_tb/54005228/sim.vcd & ``` -------------------------------- ### hr.start(sim_options) Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.pdf Starts a regression run with optional simulation options. The sim_options parameter allows passing extra commands to the simulator executor call. ```APIDOC ## [START] hr.start(sim_options) ### Description Starts a regression run with optional simulation options. The sim_options parameter allows passing extra commands to the simulator executor call. ### Method START ### Endpoint hr.start(sim_options) ### Parameters #### Path Parameters - **sim_options** (string) - Optional - Extra commands to add to the simulator executor call. ### Request Example hr.start(sim_options="-t ps -do\"quietly set NumericStdNoWarnings 1\"") ### Response #### Success Response (200) - **status** (string) - Description: Indicates the start of the regression run. #### Response Example { "status": "started" } ``` -------------------------------- ### run_command Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.pdf Executes a command by HDLRegression at the given stage in the regression script. Pre-simulation commands must be called prior to start() and post-simulation commands after start(). ```APIDOC ## run_command ### Description Executes a command by HDLRegression at the given stage in the regression script. Pre-simulation commands must be called prior to start() and post-simulation commands after start(). ### Method run_command ### Endpoint hr.run_command(, ) ### Parameters #### Path Parameters - **command** (string) - Required - The command to execute. - **verbose** (boolean) - Optional - If True, prints output to the terminal. Default is False. ### Request Example ```python hr.run_command('python3 ../script/run_spec_cov.py --config ../script/config.txt') hr.run_command('vsim -version', verbose=True) ``` ### Response No response body. The method executes the command. ### Notes Relative paths will be relative to the regression script and not where the regression script is called from. ``` -------------------------------- ### Run test in GUI mode with ModelSim/QuestaSim/Rivier-PRO Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/latex/hdlregression.pdf Launches the regression script inside the simulator GUI with a loaded test case ready to run. Use -g or --gui. ```bash python ../test/regression.py -tc uart_vvc_tb.func.check_simple_transmit -g ``` -------------------------------- ### Run pre-processing in parallel, simulations sequentially Source: https://github.com/hdlutils/hdlregression/blob/main/doc/src/_build/html/cli.html Enables parallel pre-processing while test case simulations run sequentially. Use the -t flag without a number. ```bash > python ../test/regression.py -tg receive_tests -t ```