Creating a parametrized IP core generator using the CoreTML framework

This document describes the suggested workflow for creating a parametrized Verilog/VHDL IP core generator using the CoreTML framework. This workflow is not intended to fit every possible scenario, but to be a decent starting point.

CoreTML framework distribution includes some simple parametrized IP core examples, including testbenches for automatic verification.

See also the CoreTML framework tutorial.

IP core template design

Create an ordinary (non-parametrized) design

This preliminary step is optional. Sometimes (especially in complex cases) it can be easier to start with a plain, non-parametrized Verilog (or VHDL) design. This design should be then simulated and debugged as usual.

Generate a basic template

Existing HDL source file (files) can be converted to TML template (templates). These automatically generated TML templates don't take any parameters and will yield the original source file when processed by TMLgen.

The conversion is done using the maketml tool that can be invoked from the command line or from the CoreTML Editor. maketml can generate two types of templates: those using ordinary (default) formatting mode and those using strict formatting mode. These template types are semantically equivalent but their syntax rules slightly differ. Strict formatting mode allows the developer to maintain proper output file indentation while keeping reasonable TML template formatting. It is suggested that you use strict formatting mode unless your file contains less than a couple of dozens lines.

To convert from the command line, type:

maketml --strict inputfile.vhd outputfile.tml

Alternatively, one can invoke Run->Generate TML template (strict formatting) menu command from the CoreTML Editor.

Define the template parameters

Now one should use the \parameters tag to define what parameters will be accepted by the template. This tag is entirely optional (a TML template is perfectly valid without it), but it makes the latter steps much easier.

To define a required parameter, use the \req subtag of the \parameters tag. Allowed arguments for \req are name (parameter name) and type (parameter type, can be number, string, boolean or table). To define an optional parameter, use the \opt subtag. It allows the same arguments as \req and one additional argument: default (default parameter value).

It can be easier to declare all parameters at optional at this point, and define their default values in such a way that the output file should repeat the initial (i.e. non-parametrized) design. This allows you not to pass template parameters during template elaboration and debug. After that you may want to delete these default values.

Elaborate the template

Use the CoreTML tags to replace non-parametrized template description with the parametrized one. Refer to the Template Markup Language Reference. If you are using the CoreTML Editor and have set default value for all template parameters (see previous paragraph), one can use Run->Go menu item or simply F5 key to process the template (the output content will be shown in the output window). Otherwise, invoke TMLgen from the command line as follows:

tmlgen template.tml outputfile.vhd

Create a configuration GUI

Configuration GUI descriptions for TMLconf (see screenshot) are written in TML-c language. CoreTML includes a simple tool named gentmc that can be used to generate basic interface description. This tool can only be applied of the template properly defines its parameters via the \parameters tag:

gentmc --relative template.tml interface.tmc

Alternatively, one can use the Run->Generate configuration interface description menu command from the CoreTML editor.

Verifying a parametrized template

Verification of parametrized templates can be somewhat challenging. One should take the following points into account:

• A testbench must provide a non-interactive mode with an automatic result comparison.
• A separate TML template should be created to generate a testbench for any particular IP core configuration. For SystemC testbenches it can be easier to generate a header file containing appropriate macro definitions.
• A script should be written which chooses core parameters, generates an IP core and a testbench, and runs a simulator to verify the design. Parameters can be chosen randomly or sequentially, depending on the task.
• If some parameter combinations are considered inappropriate or invalid, the aforementioned script shouldn't choose that parameter combination. In this case, the IP core template itself should also check for a such condition and issue an error message if the user tries to instantiate it with invalid parameters.