# Magia
> Asta e magia ea a căntat.
## What is Magia?
Magia generates Synthesizable SystemVerilog in pythonic syntax.
The goal of Magia is
- To provide a simple and intuitive way to generate HDL code.
- Take advantage of the Python to produce reconfigurable, reusable HDL code.
## What is not Magia?
- Magia **IS NOT** a High Level Synthesis (HLS) framework, which compile arbitrary Python code into HDL.
- Magia **DOES NOT** support simulation.
- Major reason is we have reliable and mature simulation tools like
- [cocotb](https://www.cocotb.org/)
- [verilator](https://www.veripool.org/verilator/)
- We want to focus on the Design Capturing / HDL generation part, instead of rebuilding the whole workflow.
## Project Roadmap
Please refer to the [Magia Roadmap](docs/roadmap.md).
## Installation
```bash
pip install syn-magia
```
## Examples
Magia generates Synthesizable SystemVerilog code with the following command:
Refer the [Syntax Documentation](docs/syntax.md) for more details.
```python
from magia import Elaborator, Module, Input, Output
# Define a module
class TopLevel(Module):
def __init__(self, width, **kwargs):
super().__init__(**kwargs)
# Define IO ports
self.io += [
Input("clk", 1),
Input("a", width),
Input("b", width),
Output("dout", width),
]
# Implement the logic
clk = self.io.clk
self.io.dout <<= (self.io.a + self.io.b).reg(clk)
# Specialize the module
top = TopLevel(width=16, name="TopModule")
# Elaborate SystemVerilog code
result = Elaborator.to_string(top)
# Obtain SystemVerilog code of the top module
sv_code_of_top = Elaborator.to_dict(top)["TopModule"]
# Write SystemVerilog code to a directory
Elaborator.to_files("/tmp/output_dir", top)
```
### Simulation with cocotb
Although Magia does not support simulation, we can use [cocotb](https://www.cocotb.org/) to simulate the generated code.
Make sure you have installed cocotb and simulator required (e.g. [verilator](https://www.veripool.org/verilator/)).
```python
import cocotb
from cocotb.runner import get_runner
from magia import Elaborator, Module
from pathlib import Path
TOP_LEVEL_NAME = "TopLevel"
OUTPUT_FILE = "TopLevel.sv"
# Define a module
class TopLevel(Module):
...
# Define your test
@cocotb.test()
async def test_smoke(dut):
...
if __name__ == "__main__":
# Elaborate SystemVerilog code to a file
Elaborator.to_file(OUTPUT_FILE, TopLevel(width=16, name=TOP_LEVEL_NAME))
runner = get_runner("verilator")
runner.build(
verilog_sources=[OUTPUT_FILE],
hdl_toplevel=TOP_LEVEL_NAME,
always=True,
)
runner.test(
hdl_toplevel=TOP_LEVEL_NAME,
testcase="test_smoke",
# Let cocotb locates this file
test_dir=Path(__file__).parent.absolute(),
test_module=Path(__file__).stem,
)
```
## Documentation
- [Syntax Documentation](docs/syntax.md)
- [Elaborate Designs](docs/elaborate.md)
- [Memory Syntax](docs/memory.md)
- [External Module](docs/external_module.md)
## Contributing
The project is still a personal project, in a very early stage.
Feel free to open an issue for any bug / feature wishlist.
We also have a [Contribution Guideline](docs/CONTRIBUTING.md) and [Code of Conduct](docs/CODE_OF_CONDUCT.md).
Please take a look before you contribute.
In case you are interested in this project, contact me via:
https://github.com/khwong-c
## Reference
There are many attempts to generate HDL code in Python.
Similar projects are listed below:
- [Amaranth/nMigen](https://github.com/amaranth-lang/amaranth)
- [PyRTL](https://pyrtl.readthedocs.io/)
- [MyHDL](http://www.myhdl.org/)
- [Pyverilog](https://github.com/PyHDI/Pyverilog)
Raw data
{
"_id": null,
"home_page": "",
"name": "syn-magia",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "Verilog HDL,SystemVerilog,Synthesizable,RTL,HDL,Hardware Description Language,Code Generation,FPGA,ASIC,EDA,RTL Design",
"author": "khwong-c64",
"author_email": "kin.hin.wong.c@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1f/65/1dda568c8cb81676fb0e249b3fc1cc28158b4140c1836802f1273c35c676/syn_magia-0.3.0.tar.gz",
"platform": null,
"description": "# Magia\n\n> Asta e magia ea a c\u0103ntat.\n\n## What is Magia?\n\nMagia generates Synthesizable SystemVerilog in pythonic syntax.\n\nThe goal of Magia is\n\n- To provide a simple and intuitive way to generate HDL code.\n- Take advantage of the Python to produce reconfigurable, reusable HDL code.\n\n## What is not Magia?\n\n- Magia **IS NOT** a High Level Synthesis (HLS) framework, which compile arbitrary Python code into HDL.\n- Magia **DOES NOT** support simulation.\n - Major reason is we have reliable and mature simulation tools like\n - [cocotb](https://www.cocotb.org/)\n - [verilator](https://www.veripool.org/verilator/)\n - We want to focus on the Design Capturing / HDL generation part, instead of rebuilding the whole workflow.\n\n\n\n## Project Roadmap\n\nPlease refer to the [Magia Roadmap](docs/roadmap.md).\n\n## Installation\n\n```bash\npip install syn-magia\n```\n\n## Examples\n\nMagia generates Synthesizable SystemVerilog code with the following command:\n\nRefer the [Syntax Documentation](docs/syntax.md) for more details.\n\n```python\nfrom magia import Elaborator, Module, Input, Output\n\n\n# Define a module\nclass TopLevel(Module):\n def __init__(self, width, **kwargs):\n super().__init__(**kwargs)\n # Define IO ports\n self.io += [\n Input(\"clk\", 1),\n Input(\"a\", width),\n Input(\"b\", width),\n Output(\"dout\", width),\n ]\n\n # Implement the logic\n clk = self.io.clk\n self.io.dout <<= (self.io.a + self.io.b).reg(clk)\n\n\n# Specialize the module\ntop = TopLevel(width=16, name=\"TopModule\")\n\n# Elaborate SystemVerilog code\nresult = Elaborator.to_string(top)\n\n# Obtain SystemVerilog code of the top module\nsv_code_of_top = Elaborator.to_dict(top)[\"TopModule\"]\n\n# Write SystemVerilog code to a directory\nElaborator.to_files(\"/tmp/output_dir\", top)\n```\n\n### Simulation with cocotb\n\nAlthough Magia does not support simulation, we can use [cocotb](https://www.cocotb.org/) to simulate the generated code.\n\nMake sure you have installed cocotb and simulator required (e.g. [verilator](https://www.veripool.org/verilator/)).\n\n```python\nimport cocotb\nfrom cocotb.runner import get_runner\nfrom magia import Elaborator, Module\nfrom pathlib import Path\n\nTOP_LEVEL_NAME = \"TopLevel\"\nOUTPUT_FILE = \"TopLevel.sv\"\n\n\n# Define a module\nclass TopLevel(Module):\n ...\n\n\n# Define your test\n@cocotb.test()\nasync def test_smoke(dut):\n ...\n\n\nif __name__ == \"__main__\":\n # Elaborate SystemVerilog code to a file\n Elaborator.to_file(OUTPUT_FILE, TopLevel(width=16, name=TOP_LEVEL_NAME))\n\n runner = get_runner(\"verilator\")\n runner.build(\n verilog_sources=[OUTPUT_FILE],\n hdl_toplevel=TOP_LEVEL_NAME,\n always=True,\n )\n runner.test(\n hdl_toplevel=TOP_LEVEL_NAME,\n testcase=\"test_smoke\",\n\n # Let cocotb locates this file\n test_dir=Path(__file__).parent.absolute(),\n test_module=Path(__file__).stem,\n )\n```\n\n## Documentation\n\n- [Syntax Documentation](docs/syntax.md)\n- [Elaborate Designs](docs/elaborate.md)\n- [Memory Syntax](docs/memory.md)\n- [External Module](docs/external_module.md)\n\n## Contributing\n\nThe project is still a personal project, in a very early stage.\nFeel free to open an issue for any bug / feature wishlist.\n\nWe also have a [Contribution Guideline](docs/CONTRIBUTING.md) and [Code of Conduct](docs/CODE_OF_CONDUCT.md).\nPlease take a look before you contribute.\n\nIn case you are interested in this project, contact me via:\nhttps://github.com/khwong-c\n\n## Reference\n\nThere are many attempts to generate HDL code in Python.\nSimilar projects are listed below:\n\n- [Amaranth/nMigen](https://github.com/amaranth-lang/amaranth)\n- [PyRTL](https://pyrtl.readthedocs.io/)\n- [MyHDL](http://www.myhdl.org/)\n- [Pyverilog](https://github.com/PyHDI/Pyverilog)",
"bugtrack_url": null,
"license": "LICENSE",
"summary": "Magia generates Synthesizable SystemVerilog in pythonic syntax",
"version": "0.3.0",
"project_urls": null,
"split_keywords": [
"verilog hdl",
"systemverilog",
"synthesizable",
"rtl",
"hdl",
"hardware description language",
"code generation",
"fpga",
"asic",
"eda",
"rtl design"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "97d01887068d85b1769f9ef48fa1b31aa24fe3adbb911ab2599ee1c53bf44bf8",
"md5": "766db1264e95c29a9d6863a288b7e210",
"sha256": "e311bafde2c6dbd71a69b052d91c0d577d643937f5e6c810391ebf15a5ccde0a"
},
"downloads": -1,
"filename": "syn_magia-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "766db1264e95c29a9d6863a288b7e210",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 29179,
"upload_time": "2024-01-06T20:57:00",
"upload_time_iso_8601": "2024-01-06T20:57:00.873004Z",
"url": "https://files.pythonhosted.org/packages/97/d0/1887068d85b1769f9ef48fa1b31aa24fe3adbb911ab2599ee1c53bf44bf8/syn_magia-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1f651dda568c8cb81676fb0e249b3fc1cc28158b4140c1836802f1273c35c676",
"md5": "e0df3218143dfa125dceb996d73cb701",
"sha256": "404ede55919eabce4121dc4cba760477164c6fad082883ea2d919ca5c2f46682"
},
"downloads": -1,
"filename": "syn_magia-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "e0df3218143dfa125dceb996d73cb701",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 26634,
"upload_time": "2024-01-06T20:57:03",
"upload_time_iso_8601": "2024-01-06T20:57:03.194352Z",
"url": "https://files.pythonhosted.org/packages/1f/65/1dda568c8cb81676fb0e249b3fc1cc28158b4140c1836802f1273c35c676/syn_magia-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-06 20:57:03",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "syn-magia"
}
JSON