edalize


Nameedalize JSON
Version 0.5.4 PyPI version JSON
download
home_pagehttps://github.com/olofk/edalize
SummaryLibrary for interfacing EDA tools such as simulators, linters or synthesis tools, using a common interface
upload_time2023-12-11 11:49:52
maintainer
docs_urlNone
authorOlof Kindgren
requires_python>=3.6, <4
licenseBSD-2-Clause
keywords vhdl verilog eda hdl rtl synthesis fpga simulation xilinx altera
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            .. image:: https://img.shields.io/readthedocs/edalize?longCache=true&style=flat-square&label=edalize.rtfd.io&logo=ReadTheDocs&logoColor=e8ecef
        :target: https://edalize.readthedocs.io/en/latest/?badge=latest
        :alt: Documentation Status

.. image:: https://img.shields.io/badge/Chat-on%20gitter-4db797.svg?longCache=true&style=flat-square&logo=gitter&logoColor=e8ecef
   :alt: Join the chat at https://gitter.im/librecores/edalize
   :target: https://gitter.im/librecores/edalize?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge

.. image:: https://img.shields.io/pypi/dm/edalize.svg?longCache=true&style=flat-square&logo=PyPI&logoColor=e8ecef&label=PyPI%20downloads
        :target: https://pypi.org/project/edalize/
        :alt: PyPI downloads

.. image:: https://img.shields.io/github/actions/workflow/status/olofk/edalize/ci.yml?branch=main&longCache=true&style=flat-square&label=CI&logo=github%20actions&logoColor=e8ecef
        :target: https://github.com/olofk/edalize/actions/workflows/CI.yml
        :alt: CI status

Edalize
=======

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).

Award-winning `Edalize introduction video`_

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.
Find the sources at `github.com/olofk/edalize <https://github.com/olofk/edalize>`__.
Once downloaded, we can install it with following Python command::

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

The reporting modules have been made optional due to their use of a number of dependencies for data analysis.
These can be installed with::

    $ python -m pip install -e ".[reporting]"

How to use it?
--------------

Ok, this sounds great.
Now, how do I get started?
Find the documentation at `edalize.rtfd.io <https://edalize.rtfd.io>`__.

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 <https://github.com/fusesoc/blinky>`_ and for
``vlog_tb_utils.v`` in `orpsoc-cores <https://github.com/fusesoc/vlog_tb_utils/blob/master/vlog_tb_utils.v>`_.

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.

.. _`Edalize introduction video`: https://www.youtube.com/watch?v=HuRtkpZqB34

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/olofk/edalize",
    "name": "edalize",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.6, <4",
    "maintainer_email": "",
    "keywords": "VHDL,verilog,EDA,hdl,rtl,synthesis,FPGA,simulation,Xilinx,Altera",
    "author": "Olof Kindgren",
    "author_email": "olof.kindgren@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/d1/67/b7d92383dc424da8a18f7eec778f1dc5ec21578017260f1b2cdb55d1e770/edalize-0.5.4.tar.gz",
    "platform": null,
    "description": ".. image:: https://img.shields.io/readthedocs/edalize?longCache=true&style=flat-square&label=edalize.rtfd.io&logo=ReadTheDocs&logoColor=e8ecef\n        :target: https://edalize.readthedocs.io/en/latest/?badge=latest\n        :alt: Documentation Status\n\n.. image:: https://img.shields.io/badge/Chat-on%20gitter-4db797.svg?longCache=true&style=flat-square&logo=gitter&logoColor=e8ecef\n   :alt: Join the chat at https://gitter.im/librecores/edalize\n   :target: https://gitter.im/librecores/edalize?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge\n\n.. image:: https://img.shields.io/pypi/dm/edalize.svg?longCache=true&style=flat-square&logo=PyPI&logoColor=e8ecef&label=PyPI%20downloads\n        :target: https://pypi.org/project/edalize/\n        :alt: PyPI downloads\n\n.. image:: https://img.shields.io/github/actions/workflow/status/olofk/edalize/ci.yml?branch=main&longCache=true&style=flat-square&label=CI&logo=github%20actions&logoColor=e8ecef\n        :target: https://github.com/olofk/edalize/actions/workflows/CI.yml\n        :alt: CI status\n\nEdalize\n=======\n\nWhat's this?\n------------\n\nEdalize 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).\n\nAward-winning `Edalize introduction video`_\n\nAll 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.\n\nThe 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.\n\nDread 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.\n\nThis 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.\n\nIt 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.\n\nIt 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.\n\nIt 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.\n\nInstall it\n----------\n\nEdalize is a Python module.\nFind the sources at `github.com/olofk/edalize <https://github.com/olofk/edalize>`__.\nOnce downloaded, we can install it with following Python command::\n\n    $ cd edalize\n    $ python -m pip install -e .\n\nThe reporting modules have been made optional due to their use of a number of dependencies for data analysis.\nThese can be installed with::\n\n    $ python -m pip install -e \".[reporting]\"\n\nHow to use it?\n--------------\n\nOk, this sounds great.\nNow, how do I get started?\nFind the documentation at `edalize.rtfd.io <https://edalize.rtfd.io>`__.\n\nAssume we have a project that consists of a Verilog source file called ``blinky.v``.\nThen there's also a testbench called ``blinky_tb.v`` and a constraints file for synthesis called ``constraints.sdc``.\nYou can get those files from `blinky <https://github.com/fusesoc/blinky>`_ and for\n``vlog_tb_utils.v`` in `orpsoc-cores <https://github.com/fusesoc/vlog_tb_utils/blob/master/vlog_tb_utils.v>`_.\n\nFor 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.\n\nEdalize is a Python tool, then we can run it inside a Python script file or\ndirectly in the Python console.\n\nFirst we have to import Edalize objects::\n\n  from edalize import *\n\nThe os module is also required for this tutorial::\n\n  import os\n\nThen register the files to use::\n\n  work_root = 'build'\n\n  files = [\n    {'name' : os.path.relpath('blinky.v', work_root),\n     'file_type' : 'verilogSource'},\n    {'name' : os.path.relpath('blinky_tb.v', work_root),\n     'file_type' : 'verilogSource'},\n    {'name' : os.path.relpath('vlog_tb_utils.v', work_root),\n     'file_type' : 'verilogSource'}\n  ]\n\nThe design has a toplevel Verilog parameter with the name ``clk_freq_hz``\nthat accepts integers. We set its default value to ``1000``. The testbench also\nhas an option to enable waveform dumping by setting a plusarg called ``vcd``::\n\n  parameters = {'clk_freq_hz' : {'datatype' : 'int', 'default' : 1000, 'paramtype' : 'vlogparam'},\n                'vcd' : {'datatype' : 'bool', 'paramtype' : 'plusarg'}}\n\nLet Edalize know we intend to use Icarus Verilog for our simulation::\n\n  tool = 'icarus'\n\nAnd put it all into a single data structure together with some info about the toplevel and name for the project::\n\n  edam = {\n    'files'        : files,\n    'name'         : 'blinky_project',\n    'parameters'   : parameters,\n    'toplevel'     : 'blinky_tb'\n  }\n\nNow we need to get ourselves a backend object from Edalize::\n\n  backend = get_edatool(tool)(edam=edam,\n                              work_root=work_root)\n\nCreate the directory and the project files::\n\n  os.makedirs(work_root)\n  backend.configure()\n\nAt 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.\n\nBuild the simulation model::\n\n  backend.build()\n\nAnd 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::\n\n  args = {'vcd' : True}\n  backend.run(args)\n\nTada! 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.\n\nNow it's time to create an FPGA image instead\n\n\nAs you have seen, Edalize is an award-winning tool for interfacing EDA tools, so\n\n**Edalize it, don't criticize it!**\n**Edalize it, and I will advertise it!**\n\nSee source code for further details.\n\n.. _`Edalize introduction video`: https://www.youtube.com/watch?v=HuRtkpZqB34\n",
    "bugtrack_url": null,
    "license": "BSD-2-Clause",
    "summary": "Library for interfacing EDA tools such as simulators, linters or synthesis tools, using a common interface",
    "version": "0.5.4",
    "project_urls": {
        "Homepage": "https://github.com/olofk/edalize"
    },
    "split_keywords": [
        "vhdl",
        "verilog",
        "eda",
        "hdl",
        "rtl",
        "synthesis",
        "fpga",
        "simulation",
        "xilinx",
        "altera"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "d167b7d92383dc424da8a18f7eec778f1dc5ec21578017260f1b2cdb55d1e770",
                "md5": "518cb42fc3c35eccbd3c58a436f4bb25",
                "sha256": "0ac5bac1955afb28d1c7191298a30e799268ce96c0c42e25d4d95b3eaa4e9862"
            },
            "downloads": -1,
            "filename": "edalize-0.5.4.tar.gz",
            "has_sig": false,
            "md5_digest": "518cb42fc3c35eccbd3c58a436f4bb25",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6, <4",
            "size": 374186,
            "upload_time": "2023-12-11T11:49:52",
            "upload_time_iso_8601": "2023-12-11T11:49:52.187076Z",
            "url": "https://files.pythonhosted.org/packages/d1/67/b7d92383dc424da8a18f7eec778f1dc5ec21578017260f1b2cdb55d1e770/edalize-0.5.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-12-11 11:49:52",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "olofk",
    "github_project": "edalize",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "tox": true,
    "lcname": "edalize"
}
        
Elapsed time: 0.15692s