RTL interface classes

RTL package

Simulation interface package for The System Development Kit

Provides utilities to import verilog modules and VHDL entities to python environment and sutomatically generate testbenches for the most common simulation cases.

Initially written by Marko Kosunen, 2017

class rtl.rtl[source]

Adding this class as a superclass enforces the definitions for rtl simulations in the subclasses.

add_connectors()[source]: Adds custom connectors to the testbench. Also connects rtl matchlist to testbench matchlist. Custom connectors should be saved in self.custom_connectors Matchlist for these connectors should be saved in self.assignment_matchlist

property add_tb_timescale

Defines if timescale directive is added to testbench. Can be used in cases where submodules have timescale directives, and you wish to control that from the testbench toplevel. Effective only for self.lang = ‘sv’

Default: False

Type:: Bool

property assignment_matchlist: List, which signals are connected in assignment stage during testbench generation Should be a list of strings, where a string is the signal name

connect_inputs()[source]: Assigns all IOS.Members[name].Data to self.iofile_bundle.Members[ioname].Data

connect_outputs()[source]: Connects the ouput data from files to corresponding output IOs

copy_or_relink(**kwargs)[source]

If the source is a symlink, create the target as a link to original target. otherwise, copy the file.

Parameters:

src (str) – Path to source file
dst (str) – Path to destination file.

copy_rtl_sources()[source]: Copy rtl sources to self.rtlsimpath

create_connectors()[source]: Creates connector definitions from 1) From a iofile that is provided in the Data attribute of an IO. 2) IOS of the verilog DUT

property custom_connectors: Custom connectors to be added to the testbench Should be a e.g. a rtl_connector_bundle

delete_rtlsimpath()[source]: Deletes all files in rtlsimpath

delete_rtlworkpath()[source]: Deletes compilation directory Not a deleter decorator, because does not delete the property.

execute_rtl_sim()[source]: Runs the rtl simulation in external simulator

format_ios()[source]: Verilog module does not contain information if the bus is signed or not. Prior to writing output file, the type of the connecting wire defines how the bus values are interpreted.

property interactive_control_contents

Content of the interactive rtl control file (.do -file).

If this property is set, a new dofile gets written to the simulation path. This takes precedence over the file pointed by interactive_controlfile.

For example, the contents can be defined in the top testbench as:

self.interactive_control_contents="""
    add wave -position insertpoint \
    sim/:tb_inverter:A \
    sim/:tb_inverter:clock \
    sim/:tb_inverter:Z
    run -all
    wave zoom full
"""

property interactive_controlfile

Path to interactive rtl control file used in interactive simulations.

The content of the file can be defined in interactive_control_contents. If the content is not set in interactive_control -property, the do-file is read from this file path. Default path is ./interactive_control_files/modelsim/dofile.do.

property interactive_rtl

True | False (default)

Launch simulator in local machine with GUI.

property lang

Language of the testbench to support multilanguage simulators. Default vhdl | sv (default)

Type:: str

property lsf_submission

Defines submission prefix from thesdk.GLOBALS[‘LSFSUBMISSION’]. [ ToDo ] Transfer definition to thesdk entity.

Usually something like ‘bsub -K’

property name: Name of the entity Extracted from the _classfile attribute

property preserve_rtlfiles

True | False (default)

If True, do not delete testbench and copy of DUT after simulations. Useful for debugging testbench generation.

read_outfile()[source]: Reads the oputput files

property rtl_timeprecision: Defines rtl time precision. This is the smallest time step representable in simulation. This should be less than equal to rtl_timeunit. Default ‘1 ps’.

property rtl_timescale: Defines the rtl timescal. This is the time unit shown by the simulator and used in testbench delays. Default ‘1ps’

property rtl_timeunit

use rtl_timescale.

Type:: Defines rtl time unit. OBSOLETE

property rtlcmd: Command used for simulation invocation Compiled from various parameters. See source for details.

property rtlmisc

List<String>

List of manual commands to be pasted to the testbench. The strings are pasted to their own lines (no linebreaks needed), and the syntax is unchanged.

Example: creating a custom clock:

self.rtlmisc = []
self.rtlmisc.append('reg clock2;')
self.rtlmisc.append('initial clock2='b0;')
self.rtlmisc.append('always #(c_Ts2/2.0) clock2 = !clock2;')

property rtlparameters

Dictionary of parameters passed to the simulator during the simulation invocation.

Example: {‘name’ : (type,value) }

property rtlsimpath

HDL source directory for rtl simulations self.simpath + ‘/rtl’

Return type:: self.simpath + ‘/rtl’

property rtlworkpath

Work library directory for rtl compilations self.simpath +’/work’

Return type:: self.simpath +’/work’

run_rtl()[source]

Copies rtl sources to a temporary simulation directory
Creates a testbench
Defines the contens of the testbench
Creates connectors
Connects inputs
Defines IO conditions
Defines IO formats in testbench
Generates testbench contents
Exports the testbench to file
Writes input files
Executes the simulation
Read outputfiles
Connects the outputs
Cleans up the intermediate files

You should overload this method while creating the simulation and debugging the testbench.

property simdut

Source file for Device Under Test in simulations directory

Returns:

self.rtlsimpath + self.name + self.vlogext for ‘sv’ model
self.rtlsimpath + self.name + ‘.vhd’ for ‘vhdl’ model

property simtb

Testbench source file in simulations directory.

This file and it’s format is dependent on the language(s) supported by the simulator. Currently we have support only for verilog testbenches.

property simulator_control_contents

Content of the simulator rtl control file.

If this property is set, a new controlfile is written to the simulation path. This takes precedence over the file pointed by simulator_controlfile.

For example, the contents can be defined in the top testbench as:

self.simulator_control_contents="""
# Path format for signals in entities :
/top/sub/clock
"""

property simulator_controlfile

Path to simulator control file.

Different simulators use different ways to control the simulation. In simulators with integrated waveform viewer, there is only one control,file e.g ‘dofile’ and Questasim . Other option, for example used with GHDL is to control the simulator with ‘–read-wave-opt=<file>’. This property provides a method to set that filepath. It is mapped to an argument of a proper option with the simulator specific class.

The content of the file can be defined in simulator_control_contents. If the content is not set in ‘simulator_control_contents` -property, the control file read from this file path. Default is set in simulator specific property for each simulator.

property vhdlentityfiles: List of VHDL entity files to be compiled in addition to DUT

property vhdllibfileentities: List of VHDL entities to be compiled in addition to DUT provided in a file given by the ‘VHDLLIBFILE’ global variable in TheSDK.config

property vloglibfilemodules: List of verilog modules to be compiled in addition to DUT provided in a file given by the ‘VLOGLIBFILE’ global variable in TheSDK.config

property vlogmodulefiles: List of verilog modules to be compiled in addition of DUT

write_infile()[source]: Writes the input files

RTL IOfile module

Provides Verilog- and VHDL file-io related attributes and methods for TheSyDeKick RTL intereface.

Restructured from verilog_iofile by Marko Kosunen, marko.kosunen@aalto.fi 2023

class rtl.rtl_iofile.rtl_iofile(parent=None, **kwargs)[source]

Class to provide file IO for rtl simulations. When created, adds a rtl_iofile object to the parents iofile_bundle attribute. Accessible as self.iofile_bundle.Members[‘name’].

Provides methods and attributes that can be used to construct sections in Verilog testbenches, like file io routines, file open and close routines, file io routines, file io format strings and read/write conditions.

Example

Initiated in parent as:: _=rtl_iofile(self,name=’foobar’)

Parameters:

parent (object) – The parent object initializing the rtl_iofile instance. Default None
**kwargs –

namestr
Name of the file. Appended with random string during the simulation.

paramstr, -g ‘g_file_’
The string defining the testbench parameter to be be passed to the simulator at command line. Sets the paramname attribute.

ioformatstr, %d
sets the ioformat attribute.

property Data: Data value of this IO

property DictData

connector_datamap(**kwargs)[source]: Verilog_connectors is an ordered list. Order defines the assumed order of columns in the file to be read or written. This datamap provides {‘name’ : index } dictionary to assing data to correct columns. Less use for data files, more for controls

property ioformat: Formatting string for verilog file reading Default %d, i.e. content of the file is single column of integers.

property langmodule

property rtl_connectors: List for verilog connectors. These are the verilog signals/regs associated with this file

property rtl_ctstamp: Current time stamp variable name to be used in verilog testbench. Used in event type file IO.

property rtl_fclose: Verilog file close routine sting.

property rtl_fopen: Verilog file open routine string.

property rtl_fptr: Verilog file pointer name.

property rtl_io

Verilog write/read construct for file IO depending on the direction and file type (event/sample).

Returns:: Verilog code for file IO to read/write the IO file.
Return type:: str

property rtl_io_condition: Condition string that must be true in order to file IO read/write to occur. See langmodules for details.

rtl_io_condition_append(**kwargs)[source]

Append new condition string to rtl_io_condition

Parameters:: **kwargs – cond : str

property rtl_io_sync: File io synchronization condition for sample type input. Default: @(posedge clock)

property rtl_pstamp: Past time stamp variable for verilog testbench. Used in event type file IO.

property rtl_stat: Status variable name to be used in verilog testbench.

property rtl_statdef: Verilog file read status integer variable definitions and initializations strings.

property rtl_tdiff: Verilog time differencec variable. Used in event based file IO. ‘

property rtl_timescale: Timescale for RTL simulations inherited from parent

property rtlparam

Extracts the parameter name and value from simparam attribute. Used to construct the parameter definitions for Verilog testbench.

Default {‘g_file_<self.name>’, (‘string’,self.file) }

set_control_data(**kwargs)[source]

Method to define event based data value with name, time, and value. Uses a python dictionary instead of a numpy array for more efficient insertions. The ‘time’ column acts as the dictionary key, the remaining columns are stored as the value.

Parameters:: **kwargs – time: int, 0 name: str val: type undefined init: int, 0 vector of values to initialize the data. lenght should correpond to self.rtl_connectors+1

Testbench_common

Common properties and methods for RTL testbench creation and manipulation

Initially written by Marko Kosunen 20190108, marko.kosunen@aalto.fi Refactored from ‘testbench’ by Marko Kosunen 20221119, marko.kosunen@aalto.fi

class rtl.testbench_common.testbench_common(parent=None, **kwargs)[source]

Testbench class. Extends module

Parameters:

parent (object, None (mandatory to define). TheSyDeKick parent entity object for this testbench.) –
**kwargs – None

property assignment_matchlist

property connectors

property dumpfile

String

Code that generates a VCD dumpfile when running the testbench with icarus verilog. This dumpfile can be used with gtkwave.

property dut_instance: RTL module parsed from the verilog or VHDL file of the parent depending on parent.model

property lang

Description language used.

Default: sv

property rtl_timeprecision

property rtl_timescale

verilog_instance_add(**kwargs)[source]

Add verilog instance to the Bundle fro a file

Parameters:

**kwargs –

namestr: name of the module
file :: File defining the module

property verilog_instances

Verilog instances Bundle to be added to tesbench

Todo Need to handle VHDL instance too.

Testbench

Testbench utility module for TheSyDeKick. Contains attributes and methods to construct a Verilog or VHDL testbench for a provided DUT module/entity, parse its IO and parameter definitions and construct a structured testbench with clock and file IO.

Utilizes logging method from thesdk.

Initially written by Marko Kosunen 20190108, marko.kosunen@aalto.fi Refactored from ‘testbench’ by Marko Kosunen 20221119, marko.kosunen@aalto.fi

class rtl.testbench.testbench(parent=None, **kwargs)[source]

Testbench class. Extends module through ‘testbench_commom’

Executes init of testbench_common, thus having the same attributes and parameters.

Parameters:: **kwargs – See module testbench_common

property assignment_matchlist

assignments(**kwargs)[source]: Wire/signal assingment strings

property clock_definition

Clock definition string

Todo Create append mechanism to add more clocks.

connect_inputs()[source]: Define connections to DUT inputs.

property connector_definitions: Verilog register and wire definition, VHDL signal strings.

property connectors: Overload to pass values to langmodule.

property content_parameters

Parameters used inside the testbench

Dict of name: (type,value)

define_testbench()[source]: Defines the tb connectivity, creates reset and clock, and initializes them to zero

property definition

Entity definition part extracted for the file. Contains generics and IO definitions.

Overloads the property inherited from ‘module’, as wish to control whan we generate the headers.

property end_condition: RTL structure that sets the thesdk_simulation_completed to true. Default for VHDL: ‘thesdk_simulation_completed <= thesdk_file_io_completed;’

generate_contents()[source]: Call language specific contents generator.

property iofile_close: File close procedure for all IO files.

property iofile_definitions: IOfile definition strings

property iofiles

property langmodule: The language specific operation is defined with an instance of language specific class. Properties and methods return values from that class.

property misccmd

String

Miscellaneous command string corresponding to self.rtlmisc -list in the parent entity.

property parameter_definitions: Parameter and variable definition strings of the testbench

verilog_instance_add(**kwargs)[source]

Add verilog instance to the Bundle fro a file

Parameters:

**kwargs –

namestr: name of the module
file :: File defining the module

property verilog_instances

Verilog instances Bundle to be added to tesbench

Todo Need to handle VHDL instance too.

Module common

Class containing common properties and methods for all language dependent modules

Initially written by Marko Kosunen, 28.10.2022

class rtl.module_common.module_common(**kwargs)[source]

Parameters:

**kwargs –

file: str: Verilog file containing the module
name: str: Name of the module
instname: str, self.name: Name of the instance
lang: str, language of the module ‘sv’ | ‘vhdl’ not supported yet.: Default: ‘sv’

abstract property contents: Contents of the module. String containing the Verilog code after the module definition.

abstract property definition: Module definition part extracted for the file. Contains parameters and IO definitions.

abstract export(**kwargs)[source]

Method to export the module to a given file.

Parameters:: **kwargs – force: Bool

property instname

Name of the instance, when instantiated inside other module.

Default: self.name_DUT

abstract property io_signals: Bundle containing the signal connectors for IO connections.

abstract property ios: Connector bundle containing connectors for all module IOS. All the IOs are connected to signal connectors that have the same name than the IOs. This is due to fact the we have decided that all signals are connectors.

property lang

Description language used.

Default: sv

property name: Name of the module. Derived from the file name.

abstract property parameters: Parameters of the verilog module. Bundle of values of type string.

property verilog_instance: Instantioation string of the module/entity for use inside of verilog modules.

property vhdl_instance: Instantioation string of the module/entity for use inside of vhdl entities.

Module

Module import features for RTL simulation package of The System Development Kit. ‘Module’ represents verilog module or VHDL entity.

Provides utilities to import Verilog modules to python environment.

Initially written by Marko Kosunen, 2017

class rtl.module.module(**kwargs)[source]

Currently module class is just an alias for verilog_module.

Executes init of module_common, thus having the same attributes and parameters.

Parameters:: **kwargs – See module module_common

property contents: Contents of the module. String containing the Verilog code after the module definition.

property definition: Module definition part extracted for the file. Contains parameters and IO definitions.

property directives: Verilog directives affecting the whole module.

export(**kwargs)[source]

Method to export the module to a given file.

Parameters:: **kwargs – force: Bool

property header: Header configuring the e.g. libraries if needed

property instance: Instantiation string of the module. Can be used inside of the other modules.

property io_signals: Bundle containing the signal connectors for IO connections.

property ios: Connector bundle containing connectors for all module IOS. All the IOs are connected to signal connectors that have the same name than the IOs. This is due to fact the we have decided that all signals are connectors.

property langmodule: The language specific operation is defined with an instance of language specific class. Properties and methods return values from that class.

property parameters: Parameters of the verilog module. Bundle of values of type string.

System verilog class

This mixin class contains all system verilog and verilog related properties that are used by simulator specific classes.

Initially written by Marko Kosunen 30.10.20200, marko.kosunen@aalto.fi

class rtl.sv.sv.sv[source]

sv_create_connectors()[source]: Cretes verilog connector definitions from 1) From a iofile that is provided in the Data attribute of an IO. 2) IOS of the verilog DUT

property vlogcompargs: List of arguments passed to the simulator during the verilog compilation

property vlogext

File extension for verilog files

Default is ‘.sv’, but this can be overridden to support, e.g. generators like Chisel that always use the ‘.v’ prefix.

property vlogmodulefiles: List of verilog modules to be compiled in addition of DUT

property vlogsimargs: Custom parameters for verilog simulation Provide as a list of strings

property vlogsimtb: Name of the VHDL testbench

property vlogsrc

Verilog source file self.vlogsrcpath/self.name.sv

Return type:: self.vlogsrcpath + ‘/’ + self.name + self.vlogext

property vlogsrcpath

Search path for the verilogfiles self.entitypath/sv

Return type:: self.entitypath/sv

Verilog Module

Verilog module import features for RTL simulation package of The System Development Kit.

Provides utilities to import Verilog modules to python environment.

Initially written by Marko Kosunen, 2017

class rtl.sv.verilog_module.verilog_module(**kwargs)[source]

Objective:

1. Collect IO’s to database
2. collect parameters to dict
Reconstruct the module definition
1. Implement methods provide sinal connections
2. Implement methods to provide parameter assingments
Create a method to create assigned module definition, where signals are a) assigned by name b) to arbitrary name vector.
Add contents, if required, and include that to definition

Executes init of module_common, thus having the same attributes and parameters.

Parameters:: **kwargs – See module module_common

property contents: Contents of the module. String containing the Verilog code after the module definition.

property definition: Module definition part extracted for the file. Contains parameters and IO definitions.

export(**kwargs)[source]

Method to export the module. Exports self.headers+self.definition to a given file.

Parameters:: **kwargs – force: Bool

property header: Header configuring the e.g. libraries if needed

property io_signals: Bundle containing the signal connectors for IO connections.

property ios: Verilog connector bundle containing connectors for all module IOS. All the IOs are connected to signal connectors that have the same name than the IOs. This is due to fact the we have decided that all signals are connectors.

property parameters: Parameters of the verilog module. Bundle of values of type string.

property verilog_instance: Instantioation string of the module. Can be used inside of the other modules.

verilog_testbench

Verilog testbench generator utility module for TheSyDeKick. Documentation provided in ‘testbench’ class

Extends testbench_common.

Initially written by Marko Kosunen 20190108, marko.kosunen@aalto.fi Refactored from ‘testbench’ by Marko Kosunen 20221119, marko.kosunen@aalto.fi

class rtl.sv.verilog_testbench.verilog_testbench(parent=None, **kwargs)[source]

Verilog testbench class.

Executes init of testbench_common, thus having the same attributes and parameters.

Parameters:: **kwargs – See module module_common

assignments(**kwargs)[source]: Wire assingment strings

property clock_definition

Clock definition string

Todo Create append mechanism to add more clocks.

connect_inputs()[source]: Define connections to DUT inputs.

property connector_definitions: Verilog register and wire definition strings

property content_parameters

Parameters used inside the testbench

Dict : {name: (type,value)}

Example

{'c_Ts': ('integer','1/(g_Rs*1e-12)')}

define_testbench()[source]: Defines the tb connectivity, creates reset and clock, and initializes them to zero

property end_condition: Verilog structure for custom finish of the simulation. Default: ‘’

generate_contents()[source]

This is the method to generate testbench contents. Override if needed Contents of the testbench is constructed from attributes in the following order

   self.parameter_definitions
   self.connector_definitions
   self.assignments()
   self.iofile_definitions
   self.misccmd
   self.dumpfile
   self.dut_instance.verilog_instance
   self.verilog_instance_members.items().instance (for all members)
   self.connectors.verilog_inits()
   self.iofiles.Members.items().rtl_io (for all members)
   self.iofile.close (for all members)

Addtional code may be currently injected by appending desired
strings (Verilog sytax) to the relevant string attributes.

property iofile_close: File close procedure for all IO files.

property iofile_definitions: IOfile definition strings

property misccmd

String

Miscellaneous command string corresponding to self.rtlmisc -list in the parent entity.

property parameter_definitions: Parameter and variable definition strings of the testbench

Verilog connector

Class for describing signals in wide sense, including IO’s

Written by Marko Kosunen 20190109 marko.kosunen@aalto.fi

class rtl.sv.verilog_connector.verilog_connector(**kwargs)[source]

Executes init of connector_common, thus having the same attributes and parameters.

Parameters:: **kwargs – See module module_common

property assignment

bassign()[source]

property definition

property initialization

property ioformat

nbassign(**kwargs)[source]

property type: Type defaults to None mening that all signals are handled as unsigned integers. Can be explicitly set to ‘signed’ if needed for type conversion of the output signals.

VHDL class

This mixin contains all VHDL related properties that are used by the simulator specific classes.

Initially written by Marko Kosunen 30.10.20200, marko.kosunen@aalto.fi

class rtl.vhdl.vhdl.vhdl[source]

property vhdlcompargs: List of arguments passed to the simulator during VHDL compilation

property vhdlentityfiles: List of VHDL entity files to be compiled in addition to DUT

property vhdlext

File extension for verilog files

Default is ‘.vhd’, but this can be overridden.

property vhdlsimargs: Custom parameters for VHDL simulation Provide as a list of strings

property vhdlsimtb: Name of the VHDL testbench

property vhdlsrc

VHDL source file self.vhdlsrcpath/self.name.vhd’

Return type:: self.vhdlsrcpath + ‘/’ + self.name + ‘.vhd’

property vhdlsrcpath

VHDL search path self.entitypath/vhdl

Return type:: self.entitypath/vhdl

VHDL_entity

VHDL import features for RTL simulation package of The System Development Kit

Provides utilities to import VHDL entities to python environment. Imported VHDL entities will be instantiated as verilog modules, and are intended to be simulated within verilog testbench with simulator supporting cross language compilations.

Initially written by Marko Kosunen, 2017

Transferred from VHDL package in Dec 2019

class rtl.vhdl.vhdl_entity.vhdl_entity(**kwargs)[source]

Objective:

1. Collect IO’s to database
2. collect parameters to dict
Reconstruct the entity definition
1. Implement methods provide signal connections
2. Implement methods to provide generic assingments
Create a method to create assigned module definition, where signals are a) assigned by name b) to arbitrary name vector.
Add contents, if required, and include that to definition

Executes init of module_common, thus having the same attributes and parameters.

Parameters:: **kwargs – See module module_common

property contents: Contents is extracted. We do not know what to do with it yet.

property definition: Entity definition part extracted for the file. Contains generics and IO definitions.

export(**kwargs)[source]

Method to export the module. Exports self.headers+self.definition to a given file.

Parameters:: **kwargs – force: Bool

property header: Header configuring the e.g. libraries if needed

property io_signals: Bundle containing the signal connectors for IO connections.

property ios: Rtl connector bundle containing connectors for all module IOS. All the IOs are connected to signal connectors that have the same name than the IOs. This is due to fact the we have decided that all signals are connectors.

property parameters: Generics of the VHDL entity

Icarus is a mixin class used to provide simulator specific properties and methods for RTL class

Initially written by Marko kosunen 20221030

class rtl.icarus.icarus.icarus[source]

property icarus_controlfilepaths

property icarus_dofilepaths

property icarus_rtlcmd

property icarus_simdut

Source file for Device Under Test in simulations directory

Returns:

self.rtlsimpath + self.name + self.vlogext for ‘sv’ model
self.rtlsimpath + self.name + ‘.vhd’ for ‘vhdl’ model

property icarus_simtb

Icarus Testbench source file in simulations directory.

This file and it’s format is dependent on the language(s) supported by the simulator. Currently we have support only for verilog testbenches.

Questasim is a mixin class it is used to provide simulator specific properties and methods for RTL class

Initially written by Marko kosunen 20221030

class rtl.questasim.questasim.questasim[source]

property questasim_controlfilepaths

property questasim_dofilepaths

property questasim_rtlcmd

property questasim_simdut

Source file for Device Under Test in simulations directory

Returns:

self.rtlsimpath + self.name + self.vlogext for ‘sv’ model
self.rtlsimpath + self.name + ‘.vhd’ for ‘vhdl’ model

property questasim_simtb

Questasim testbench source file in simulations directory.

This file and it’s format is dependent on the language(s) supported by the simulator. Currently we have support only for verilog testbenches.