Edalize by olofk

An abstraction library for interfacing EDA tools

Edalize

CI status Documentation Status

What's this?

Edalize is a Python Library for interacting with EDA tools. It can create project files for supported tools and run them in batch or GUI mode (where supported).

All EDA tools such as Icarus, Yosys, ModelSim, Vivado, Verilator, GHDL, Quartus etc get input HDL files (Verilog and VHDL) and some tool-specific files (constraint files, memory initialization files, IP description files etc). Together with the files, perhaps a couple of Verilog `defines, some top-level parameters/generics or some tool-specific options are set. Once the configuration is done, a simulation model, netlist or FPGA image is built, and in the case of simulations, the model is also executed, maybe with some extra run-time parameters.

The thing is, all these tools are doing this in completely different ways and there's generally no way to import configurations from one simulator to another.

Dread not! Edalize takes care of this for you. By telling Edalize what files you have, together with some info, what parametrization to use at compile- and run-time (e.g. plusargs, defines, generics, parameters), VPI library sources (when applicable) and any other tool-specific options not already mentioned, it will create the necessary project files and offer to build and run it for you.

This will save you from having to deal with the boring stuff of interfacing the EDA tools yourself, while still have pretty much full power to set up the project the way you want.

It allows you to quickly switch tools, at least when it comes to simulators. This is highly useful to shake out tool-specific bugs, or just to let you work with your weapon of choice.

It can also be used to just get a quick template that you can open up in the tool's GUI if there is such, and continue working from there.

It can be directly integrated as a library for your existing Python-powered HDL project, or can be used stand-alone (soon anyway) to feed Edalize from projects written in other languages.

Install it

Edalize is a Python module. Then once downloaded we can install it with following Python command:

$ cd edalize
$ python -m pip install -e .

How to use it?

Ok, this sounds great. Now, how do I get started?

Assume we have a project that consists of a Verilog source file called blinky.v. Then there's also a testbench called blinky_tb.v and a constraints file for synthesis called constraints.sdc. You can get those files from blinky and for vlog_tb_utils.v in orpsoc-cores.

For a simulation, we want to use the two Verilog files, build it in a subdirectory called build, and then run it with a parameter to control simulated clock frequency.

Edalize is a Python tool, then we can run it inside a Python script file or directly in the Python console.

First we have to import Edalize objects:

from edalize import *

The os module is also required for this tutorial:

import os

Then register the files to use:

work_root = 'build'

files = [
  {'name' : os.path.relpath('blinky.v', work_root),
   'file_type' : 'verilogSource'},
  {'name' : os.path.relpath('blinky_tb.v', work_root),
   'file_type' : 'verilogSource'},
  {'name' : os.path.relpath('vlog_tb_utils.v', work_root),
   'file_type' : 'verilogSource'}
]

The design has a toplevel Verilog parameter with the name clk_freq_hz that accepts integers. We set its default value to 1000. The testbench also has an option to enable waveform dumping by setting a plusarg called vcd:

parameters = {'clk_freq_hz' : {'datatype' : 'int', 'default' : 1000, 'paramtype' : 'vlogparam'},
              'vcd' : {'datatype' : 'bool', 'paramtype' : 'plusarg'}}

Let Edalize know we intend to use Icarus Verilog for our simulation:

tool = 'icarus'

And put it all into a single data structure together with some info about the toplevel and name for the project:

edam = {
  'files'        : files,
  'name'         : 'blinky_project',
  'parameters'   : parameters,
  'toplevel'     : 'blinky_tb'
}

Now we need to get ourselves a backend object from Edalize:

backend = get_edatool(tool)(edam=edam,
                            work_root=work_root)

Create the directory and the project files:

os.makedirs(work_root)
backend.configure()

At this point, we still haven't run the actual EDA tool and the files in the work_root directory can be used without Edalize if that is preferred. But let's continue the example with Edalize.

Build the simulation model:

backend.build()

And finally run it, with our arguments. Some types of parameters (e.g. plusargs) are defined aat runtime, and at this point we can change their value by passing the name and new value to run(). Or we could skip it altogether, and the default value from the configure stage would be used. Let's run with VCD logging enabled:

args = {'vcd' : True}
backend.run(args)

Tada! We have simulated. As an exercise, try to just change the tool variable to e.g. modelsim, xsim or any of the other simulators supported by Edalize and see if it works without any changes.

Now it's time to create an FPGA image instead

As you have seen, Edalize is an award-winning tool for interfacing EDA tools, so

Edalize it, don't criticize it! Edalize it, and I will advertise it!

See source code for further details.

BSD 2-Clause License

Copyright (c) 2018, Olof Kindgren
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Project Meta

  • Registered on LibreCores 3 months ago
  • Project started 1 year ago
  • Last commit 23 days ago

Commits

{"labels":[2018,2019,2020],"series":[[16,109,77]]}

Commits per year

Contributors

{"labels":[2018,2019,2020],"series":[[3,20,25]]}

Unique contributors per year

Releases

v0.2.2 is is the latest of 11 releases.

  • v0.2.2
    May 27, 2020 f72286e
  • v0.2.1
    May 26, 2020 c1f5dcd
  • v0.2.0
    Mar 16, 2020 63d9512
  • v0.1.7
    Nov 7, 2019 dce74a7
  • v0.1.6
    Aug 1, 2019 99bcf8c
  • v0.1.5
    Jul 18, 2019 3ef840b
  • v0.1.4
    Jun 17, 2019 f4e908d
  • v0.1.3
    Feb 22, 2019 8970b62
  • v0.1.2
    Dec 18, 2018 dc7b53a
  • v0.1.1
    Nov 28, 2018 9cc3f14
  • v0.1
    Oct 27, 2018 f1704a1

Languages

{"labels":["Others","Python","DOS Batch","Tcl\/Tk","make","reStructuredText","Bourne Shell"],"series":[28,78,56,32,29,7,6]}

Share of languages used

Data Sheet
Project Web Site
https://github.com/olofk/edalize.git
Issue Tracker
Last activity 4 days ago
v0.2.2 released 2 months ago
Primary language: Python
34 open issues
16 open pull requests
54 forks
23 watchers
188 stars
202 commits by 37 contributors
Olof Kindgren Philipp Wagner GCHQDeveloper992 Karol Gugala Colin Marquardt
0,1,2,2,1,2,2,4,3,3,3,6,4,1,6,1,2,0,0,2,5,1,0,0,4,3,1,11,0,0,7,7,8,8,3,0,1,4,4,0,0,0,4,0,2,0,0,0,0,0

activity over the last year

LibreCores data updated 2 days ago