| Name | desyrdl JSON |
| Version |
1.3.0
JSON |
| download |
| home_page | None |
| Summary | DesyRDL - Tool for address space and register generation |
| upload_time | 2024-01-04 09:37:54 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | Apache-2.0 |
| keywords |
eda
fpga
systemrdl
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# DesyRDL
This tool generates outputs for an address space that is defined by one or many
SystemRDL™ 2.0 input files. The address space could be made up of all the
software-accessible registers and memory regions in an FPGA design, or just the
registers of a single IP block.
SystemRDL™ 2.0 is a standard released by Accellera Systems Initiative Inc
that is meant to describe such an address space, see [\[systemrdl\]](#systemrdl).
Outputs are based on templates. there is an option to use custom templates or the one provided by the tool.
The templates provided with this package are the common files for the following outputs:
* Synthesizable VHDL register logic
* Mapfiles (compatible with ChimeraTK)
* C header files
* AsciiDoc documentation
DesyRDL was developed at [DESY](https://desy.de) in the MSK firmware group as a
replacement for its existing proprietary method of register and address map
generation, the "Internal Interface", called "IBUS" in its latest version
[ii](#ii).
The use of SystemRDL™ 2.0 standard was considered for a long time,
but due to the lack of open source compilers or parsers, it was dropped.
The decision to use the SystemRDL™ 2.0 standard came after
the open source [SystemRDL compiler](https://github.com/SystemRDL/systemrdl-compiler) has been published.
This has been proposed by [MicroTCA Tech Lab](https://techlab.desy.de/) at DESY when they wrote
[HECTARE](https://github.com/MicroTCA-Tech-Lab/hectare), the predecessor of DesyRDL.
## Usage
This tool can be used standalone but was intended to be used as part of a
firmware build environment like DESY MSK's
[FPGA Firmware Framework](https://fpgafw.pages.desy.de/docs-pub/fwk/index.html),
short `fwk`.
See `desyrdl -h` for options.
All RDL files must be passed in the correct order. Below is an example for the
`test_hectare` module which also comes with a testbench (not in Git yet):
desyrdl -o out -i examples/spi_ad9510.rdl examples/test_desyrdl.rdl examples/top.rdl -f vhdl tcl
This will compile the `.rdl` file and create one `.vhd` in `./out/` for each
`addrmap` instance in the model and for each VHDL template in
`./desyrdl/templates/vhdl/`. The common files from `./desyrdl/libraries/vhdl/`
will also be copied there.
The generated VHDL logic should be integrated into your module or IP as an
entity next to the other logic. This is shown in the diagram below. Registers
and external interfaces are available on combined ports of a custom record type
(e.g. `t_addrmap_mymodule_in` and `t_addrmap_mymodule_out`). Through these
records, each node in this `addrmap` can be accessed by its SystemRDL instance
name. Check the generated VHDL package for details.
## Concept
Compiling the SystemRDL™ files is handled by
[SystemRDL Compiler](https://systemrdl-compiler.readthedocs.io/en/latest/).
To create useful information (or "context") for the template processing, its
Walker/Listener method of traversing the compiled tree is used.
`DesyListener` extends its `systemrdl.RDLListener` class. It extracts a fixed
set of information from the compiled tree and passes it on to a template engine
(Jinja2).
### Templates
Templates are written for the Jinja2 template engine. Users can provide their
own templates using `-t` switch.
### Context
Context creation differs a bit depending on the type of output. Some outputs
have to be generated for each `addrmap` component (e.g. VHDL) and others are
generated for the whole address space at once (e.g. mapfiles and the C header).
The context is a Python `dict` that contains further dictionaries to describe
register types and instances, memory types and instances, further external
components and some more. It is currently a bit of a mess.
## Supported interfaces buses
The DesyRDL allows to generate various top address map interfaces.
They are defined in the addrmap component by the `desyrdl_interface` variable.
Tool bus support and `desyrdl_interfaces` values:
| Value | Description | Bus Size | Supported |
|:---------|:--------------------------------------------------|:---------|:----------|
| AXI4L | AXI4 Lite interface | 32 bit | YES |
| IBUS | Internal Interface type bus, proprietary MSK DESY | 32 bit | YES |
| WISHBONE | Open source hardware computer bus | 32 bit | planned |
## Known Issues and Limitations
The bus decoder implementation is relatively basic:
* Only 32bit data busses
* Likewise, only 32 bit registers are supported
* The dual-port memory interface does not support AXI4 write strobes
* The logic operates on a single clock and the developer has to take care of any
CDCs
## Acknowledgements
This tool relies heavily on systemrdl-compiler by Alex Mykyta and was only
developed because it exists.
Accellera™ and SystemRDL™ are trademarks of Accellera Systems
Initiative Inc.
## References
### systemrdl
"SystemRDL 2.0 Register Description Language", Accellera
Systems Initiative Inc, 2018,
available from https://accellera.org/downloads/standards/systemrdl
### ii
"INTERNAL INTERFACE, I/O Communication with FPGA Circuits and Hardware
Description Standard for Applications in HEP and FEL Electronics ver. 1.0",
2005, available from
https://flash.desy.de/reports_publications/tesla_reports/tesla_reports_2005/
Raw data
{
"_id": null,
"home_page": null,
"name": "desyrdl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Michael B\u00fcchler <michael.buechler@desy.de>, Lukasz Butkowski <lukasz.butkowski@desy.de>",
"keywords": "EDA,FPGA,SystemRDL",
"author": null,
"author_email": "MSK DESY <msk-firmware@desy.de>, Michael B\u00fcchler <michael.buechler@desy.de>, Lukasz Butkowski <lukasz.butkowski@desy.de>",
"download_url": "https://files.pythonhosted.org/packages/2d/29/6d029745c353363266ab4327f7b6469b86bcb8222a60289239c89c5de0d6/desyrdl-1.3.0.tar.gz",
"platform": null,
"description": "# DesyRDL\n\nThis tool generates outputs for an address space that is defined by one or many\nSystemRDL™ 2.0 input files. The address space could be made up of all the\nsoftware-accessible registers and memory regions in an FPGA design, or just the\nregisters of a single IP block.\n\nSystemRDL™ 2.0 is a standard released by Accellera Systems Initiative Inc\nthat is meant to describe such an address space, see [\\[systemrdl\\]](#systemrdl).\n\nOutputs are based on templates. there is an option to use custom templates or the one provided by the tool.\nThe templates provided with this package are the common files for the following outputs:\n\n* Synthesizable VHDL register logic\n* Mapfiles (compatible with ChimeraTK)\n* C header files\n* AsciiDoc documentation\n\nDesyRDL was developed at [DESY](https://desy.de) in the MSK firmware group as a\nreplacement for its existing proprietary method of register and address map\ngeneration, the \"Internal Interface\", called \"IBUS\" in its latest version\n[ii](#ii).\n\nThe use of SystemRDL™ 2.0 standard was considered for a long time,\nbut due to the lack of open source compilers or parsers, it was dropped.\n\nThe decision to use the SystemRDL™ 2.0 standard came after\nthe open source [SystemRDL compiler](https://github.com/SystemRDL/systemrdl-compiler) has been published.\nThis has been proposed by [MicroTCA Tech Lab](https://techlab.desy.de/) at DESY when they wrote\n[HECTARE](https://github.com/MicroTCA-Tech-Lab/hectare), the predecessor of DesyRDL.\n\n## Usage\n\nThis tool can be used standalone but was intended to be used as part of a\nfirmware build environment like DESY MSK's\n[FPGA Firmware Framework](https://fpgafw.pages.desy.de/docs-pub/fwk/index.html),\nshort `fwk`.\n\nSee `desyrdl -h` for options.\nAll RDL files must be passed in the correct order. Below is an example for the\n`test_hectare` module which also comes with a testbench (not in Git yet):\n\n desyrdl -o out -i examples/spi_ad9510.rdl examples/test_desyrdl.rdl examples/top.rdl -f vhdl tcl\n\nThis will compile the `.rdl` file and create one `.vhd` in `./out/` for each\n`addrmap` instance in the model and for each VHDL template in\n`./desyrdl/templates/vhdl/`. The common files from `./desyrdl/libraries/vhdl/`\nwill also be copied there.\n\nThe generated VHDL logic should be integrated into your module or IP as an\nentity next to the other logic. This is shown in the diagram below. Registers\nand external interfaces are available on combined ports of a custom record type\n(e.g. `t_addrmap_mymodule_in` and `t_addrmap_mymodule_out`). Through these\nrecords, each node in this `addrmap` can be accessed by its SystemRDL instance\nname. Check the generated VHDL package for details.\n\n![top integration diagram](./doc/images/top_integration.svg \"Top-level integration\")\n\n## Concept\n\nCompiling the SystemRDL™ files is handled by\n[SystemRDL Compiler](https://systemrdl-compiler.readthedocs.io/en/latest/).\nTo create useful information (or \"context\") for the template processing, its\nWalker/Listener method of traversing the compiled tree is used.\n\n`DesyListener` extends its `systemrdl.RDLListener` class. It extracts a fixed\nset of information from the compiled tree and passes it on to a template engine\n(Jinja2).\n\n![DesyRDL flow diagram](./doc/images/DesyRDL.svg \"DesyRDL flow overview\")\n\n### Templates\n\nTemplates are written for the Jinja2 template engine. Users can provide their\nown templates using `-t` switch.\n\n### Context\n\nContext creation differs a bit depending on the type of output. Some outputs\nhave to be generated for each `addrmap` component (e.g. VHDL) and others are\ngenerated for the whole address space at once (e.g. mapfiles and the C header).\n\nThe context is a Python `dict` that contains further dictionaries to describe\nregister types and instances, memory types and instances, further external\ncomponents and some more. It is currently a bit of a mess.\n\n## Supported interfaces buses\n\nThe DesyRDL allows to generate various top address map interfaces.\nThey are defined in the addrmap component by the `desyrdl_interface` variable.\n\nTool bus support and `desyrdl_interfaces` values:\n\n| Value | Description | Bus Size | Supported |\n|:---------|:--------------------------------------------------|:---------|:----------|\n| AXI4L | AXI4 Lite interface | 32 bit | YES |\n| IBUS | Internal Interface type bus, proprietary MSK DESY | 32 bit | YES |\n| WISHBONE | Open source hardware computer bus | 32 bit | planned |\n\n\n## Known Issues and Limitations\n\nThe bus decoder implementation is relatively basic:\n\n* Only 32bit data busses\n* Likewise, only 32 bit registers are supported\n* The dual-port memory interface does not support AXI4 write strobes\n* The logic operates on a single clock and the developer has to take care of any\n CDCs\n\n## Acknowledgements\n\nThis tool relies heavily on systemrdl-compiler by Alex Mykyta and was only\ndeveloped because it exists.\n\nAccellera™ and SystemRDL™ are trademarks of Accellera Systems\nInitiative Inc.\n\n## References\n\n\n### systemrdl\n\n\"SystemRDL 2.0 Register Description Language\", Accellera\nSystems Initiative Inc, 2018,\navailable from https://accellera.org/downloads/standards/systemrdl\n\n### ii\n\n\"INTERNAL INTERFACE, I/O Communication with FPGA Circuits and Hardware\nDescription Standard for Applications in HEP and FEL Electronics ver. 1.0\",\n2005, available from\nhttps://flash.desy.de/reports_publications/tesla_reports/tesla_reports_2005/\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "DesyRDL - Tool for address space and register generation",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://gitlab.desy.de/fpgafw/tools/desyrdl",
"Issues": "https://gitlab.desy.de/fpgafw/tools/desyrdl/-/issues",
"Source": "https://gitlab.desy.de/fpgafw/tools/desyrdl"
},
"split_keywords": [
"eda",
"fpga",
"systemrdl"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "095637d96d45824873e341f64f0a30b0d5d5f0ff059c29183fc47c936b9e7041",
"md5": "50ad94af9c8f8017ed747b9577977ecc",
"sha256": "9de6fb4d8ecd3fe2cff8344468dd400e6c45c7ddfa342c1c66759274ded7ff03"
},
"downloads": -1,
"filename": "desyrdl-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "50ad94af9c8f8017ed747b9577977ecc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 48839,
"upload_time": "2024-01-04T09:37:56",
"upload_time_iso_8601": "2024-01-04T09:37:56.824809Z",
"url": "https://files.pythonhosted.org/packages/09/56/37d96d45824873e341f64f0a30b0d5d5f0ff059c29183fc47c936b9e7041/desyrdl-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2d296d029745c353363266ab4327f7b6469b86bcb8222a60289239c89c5de0d6",
"md5": "a7fa1a34ebc1f46df8dcbb403ebf9098",
"sha256": "62be71d196fd4d4d1678927e25719375216e50281dd58b097fc9e4ef48bbbde5"
},
"downloads": -1,
"filename": "desyrdl-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "a7fa1a34ebc1f46df8dcbb403ebf9098",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 41836,
"upload_time": "2024-01-04T09:37:54",
"upload_time_iso_8601": "2024-01-04T09:37:54.895325Z",
"url": "https://files.pythonhosted.org/packages/2d/29/6d029745c353363266ab4327f7b6469b86bcb8222a60289239c89c5de0d6/desyrdl-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-04 09:37:54",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "desyrdl"
}
