# 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 magia-hdl
# Install with full dependencies if advanced features are required
pip install magia-hdl[full]
```
## 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)
- [Bundle Syntax](docs/bundle.md)
- [Memory Syntax](docs/memory.md)
- [External Module](docs/external_module.md)
## Related Projects
- [Magia Flow](https://www.github.com/magia-hdl/magia-flow): Design flow integration and automation with Magia.
- [Magia IP](https://www.github.com/magia-hdl/magia-ip): IP libraries designed with Magia.
## 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": "magia-hdl",
"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/5f/63/caa49d900e5daaa0092557d91dc09f5d8c1fb903efe7da83576bd49242bf/magia_hdl-0.5.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 magia-hdl\n\n# Install with full dependencies if advanced features are required\n\npip install magia-hdl[full]\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- [Bundle Syntax](docs/bundle.md)\n- [Memory Syntax](docs/memory.md)\n- [External Module](docs/external_module.md)\n\n## Related Projects\n\n- [Magia Flow](https://www.github.com/magia-hdl/magia-flow): Design flow integration and automation with Magia.\n- [Magia IP](https://www.github.com/magia-hdl/magia-ip): IP libraries designed with Magia.\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)\n",
"bugtrack_url": null,
"license": "LICENSE",
"summary": "Magia generates Synthesizable SystemVerilog in pythonic syntax",
"version": "0.5.0",
"project_urls": {
"Repository": "https://github.com/magia-hdl/magia"
},
"split_keywords": [
"verilog hdl",
"systemverilog",
"synthesizable",
"rtl",
"hdl",
"hardware description language",
"code generation",
"fpga",
"asic",
"eda",
"rtl design"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e6311192288c8b88bcc43246a7aed467a005797c92bfc491fd60b5f41468376b",
"md5": "d7fc60fcd6d7e5094f4845291c62e02c",
"sha256": "0193aa571d1a7a7ed5d3dfb7da2c214b5e5a7f498b29fe0f7c856d11d9c9dc44"
},
"downloads": -1,
"filename": "magia_hdl-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d7fc60fcd6d7e5094f4845291c62e02c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 34291,
"upload_time": "2024-02-20T20:35:41",
"upload_time_iso_8601": "2024-02-20T20:35:41.273693Z",
"url": "https://files.pythonhosted.org/packages/e6/31/1192288c8b88bcc43246a7aed467a005797c92bfc491fd60b5f41468376b/magia_hdl-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5f63caa49d900e5daaa0092557d91dc09f5d8c1fb903efe7da83576bd49242bf",
"md5": "cd5f71d443543475d674f0f47134731b",
"sha256": "4b95124c3b4d90f13e2148456d4f93753d1afa13810f6f03e50ffa2d3c1caa63"
},
"downloads": -1,
"filename": "magia_hdl-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "cd5f71d443543475d674f0f47134731b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 30853,
"upload_time": "2024-02-20T20:35:45",
"upload_time_iso_8601": "2024-02-20T20:35:45.913482Z",
"url": "https://files.pythonhosted.org/packages/5f/63/caa49d900e5daaa0092557d91dc09f5d8c1fb903efe7da83576bd49242bf/magia_hdl-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-20 20:35:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "magia-hdl",
"github_project": "magia",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "magia-hdl"
}
JSON
