# Seal5
> [!NOTE]
> Starting **July 11, 2024** we will be offering (monthly) Seal5 Development/User meetings.
>
> Next call: **Sep 12, 2024, 11:00**
>
> Click [here](https://github.com/tum-ei-eda/seal5/discussions/104) for details, if you are interested!
> [!NOTE]
> Seal5 was recently presented at the RISC-V Summit Europe 2024. Click [here](https://github.com/tum-ei-eda/seal5/discussions/107) to access the poster, slides & recording.
[](https://pypi.org/project/seal5)
[](https://seal5.readthedocs.io/en/latest/?version=latest)
[](https://github.com/tum-ei-eda/seal5/blob/main/LICENSE)
[](https://github.com/tum-ei-eda/seal5/actions/workflows/demo.yml)
## Overview
The RISC-V instruction set architecture (ISA) is popular for its extensibility. However, a quick exploration of instruction candidates fails due to the lack of tools to auto-generate embedded software toolchain support. Seal5 work establishes a semi-automated flow to generate LLVM compiler support for custom instructions based on the CoreDSL2 ISA description language. Seal5 is capable of generating support for functionalities ranging from baseline assembler-level support, over builtin functions to compiler code generation patterns for scalar as well as vector instructions, while requiring no deeper compiler know-how.
Eliminating manual efforts for Retargeting is crutial for the automated exploration of custom RISC-V instructions as depicted in the following image. Seal5's code-generation support allows to make use of custom instructions without needing to make changes to the programs/benchmarks source code (i.e. adding inline-assembly calls).
## Prerequisites
To be able to run the examples, make sure to clone the Seal5 repo using the `--recursive` flag. Otherwise run the following command to fetch (and update) the referenced submodules.
```sh
git submodule update --init --recursive
```
### Ubuntu Packages
First, a set of APT packages needs to be installed:
```sh
sudo apt install python3-pip python3-venv cmake make ninja-build
```
### Python Requirements
First, setup a virtual environment with Python v3.8 or newer.
Install all required python packages using the following command:
`pip install -r requirements.txt`.
For development (linting, packaging,...) there are a few more dependencies which can be installed via:
`pip install -r requirements_dev.txt`.
### System Requirements
The initial cloning of the `llvm-project` repo will take a long time, hence a good internet connection is recommended. To run the demo, make sure to have at least 20GB (>40GB for debug builds) of disk space available in the destination (`/tmp/seal5_llvm_demo`) directory. The target directory can be changed as follows: `DEST=$HOME/seal5_demo`.
### Installation
**Warning:** It is highly recommended to install `seal5` into a new virtual environment. Follow these steps to initialize and enter a venv in your seal5 repo directory:
```sh
# alternative: python3 -m venv venv
virtualenv -p python3.8 venv
source venv/bin/activate
```
#### From PyPI
```
pip install seal5
```
#### Local Development Version
First prepare your shell by executing `export PYTHONPATH=$(pwd):$PYTHONPATH` inside the seal5 repository. Then you should be able to use Seal5 without needing to reinstall it.
Alternatively you should be able to use `pip install -e .`.
## Usage
### Python API
The flow can be sketched as follows (see Example below for functional code!):
```python
# Create flow
seal5_flow = Seal5Flow(...)
# Initialize LLVM repo and .seal5 directories
seal5_flow.initialize(...)
# Optional: remove artifacts from previous builds
seal5_flow.reset(...)
# Install Seal5 dependencies (CDSL2LLVM/PatternGen)
seal5_flow.setup(...)
# Load CoreDSL2+CFG files (Git config, filters,...)
seal5_flow.load(...)
# Transform Seal5 model (Extract side effects, operands,...)
seal5_flow.transform(...)
# Generate patches based on Seal5 model (ISel patterns, RISC-V features,...)
seal5_flow.generate(...)
# Apply generated (and manual) patches to LLVM codebase
seal5_flow.patch(...)
# Build patches LLVM (This will take a while)
seal5_flow.build(...)
# Run LLVM+Seal5 tests to verify functionality
seal5_flow.test(...)
# Combine patches and install LLVM
seal5_flow.deploy(...)
# Archive final LLVM (optionally inclusing logs, reports,...)
seal5_flow.export(...)
# Optional: Cleanup all artifacts
seal5_flow.cleanup(...)
```
### Command-Line Interface
Command line interface is aligned with the Python API. See `examples/demo.sh` for an full usage example
```sh
export SEAL5_HOME=...
seal5 --dir $SEAL5_HOME reset --settings
seal5 init [--non-interactive] [-c]
seal5 load --files ...
seal5 setup ...
seal5 transform ...
seal5 generate ...
seal5 patch ...
seal5 build ...
seal5 test ...
seal5 deploy ...
seal5 export ...
seal5 clean [--temp] [--patches] [--models] [--inputs]
```
## Examples
See [`examples/demo.py`](https://github.com/tum-ei-eda/seal5/blob/main/examples/demo.py) for example of end-to-end flow!
## Documentation
Checkout [Seal5's ReadTheDocs Page](https://seal5.readthedocs.io/en/latest/?version=latest)!
## Limitations
See [here](https://github.com/tum-ei-eda/seal5/blob/main/LIMITATIONS.md).
## CI/CD Flow
We added a (manual) CI job to run the `examples/demo.py` script via GitHub actions.
## Contributions
Seal5 issue tracker: https://github.com/tum-ei-eda/seal5/issues
CoreDSL2LLVM/PatternGen issue tracker: https://github.com/mathis-s/CoreDSL2LLVM/issues
## References
N/A
## Acknowledgment
<img src="./BMBF_gefoerdert_2017_en.jpg" alt="drawing" height="75" align="left" >
This research is partially funded by the German Federal Ministry of Education and Research (BMBF) within
the projects [Scale4Edge](https://www.edacentrum.de/scale4edge/) (grant number 16ME0465) and [MANNHEIM-FlexKI](https://www.edacentrum.de/projekte/MANNHEIM-FlexKI) (grant number 01IS22086L).
Raw data
{
"_id": null,
"home_page": "https://github.com/tum-ei-eda/seal5",
"name": "seal5",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "seal5",
"author": "TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation",
"author_email": "philipp.van-kempen@tum.de",
"download_url": "https://files.pythonhosted.org/packages/ab/cf/629d9838515d4a414fac8d5f43c86c197d6f9e9aa9d3c93da98153aeca27/seal5-0.2.0.tar.gz",
"platform": null,
"description": "# Seal5\n\n> [!NOTE]\n> Starting **July 11, 2024** we will be offering (monthly) Seal5 Development/User meetings.\n>\n> Next call: **Sep 12, 2024, 11:00**\n>\n> Click [here](https://github.com/tum-ei-eda/seal5/discussions/104) for details, if you are interested!\n\n> [!NOTE]\n> Seal5 was recently presented at the RISC-V Summit Europe 2024. Click [here](https://github.com/tum-ei-eda/seal5/discussions/107) to access the poster, slides & recording.\n\n[](https://pypi.org/project/seal5)\n[](https://seal5.readthedocs.io/en/latest/?version=latest)\n[](https://github.com/tum-ei-eda/seal5/blob/main/LICENSE)\n\n[](https://github.com/tum-ei-eda/seal5/actions/workflows/demo.yml)\n\n## Overview\n\nThe RISC-V instruction set architecture (ISA) is popular for its extensibility. However, a quick exploration of instruction candidates fails due to the lack of tools to auto-generate embedded software toolchain support. Seal5 work establishes a semi-automated flow to generate LLVM compiler support for custom instructions based on the CoreDSL2 ISA description language. Seal5 is capable of generating support for functionalities ranging from baseline assembler-level support, over builtin functions to compiler code generation patterns for scalar as well as vector instructions, while requiring no deeper compiler know-how.\n\nEliminating manual efforts for Retargeting is crutial for the automated exploration of custom RISC-V instructions as depicted in the following image. Seal5's code-generation support allows to make use of custom instructions without needing to make changes to the programs/benchmarks source code (i.e. adding inline-assembly calls).\n\n\n\n## Prerequisites\n\nTo be able to run the examples, make sure to clone the Seal5 repo using the `--recursive` flag. Otherwise run the following command to fetch (and update) the referenced submodules.\n\n```sh\ngit submodule update --init --recursive\n```\n\n### Ubuntu Packages\n\nFirst, a set of APT packages needs to be installed:\n\n```sh\nsudo apt install python3-pip python3-venv cmake make ninja-build\n```\n\n### Python Requirements\n\nFirst, setup a virtual environment with Python v3.8 or newer.\n\nInstall all required python packages using the following command:\n\n`pip install -r requirements.txt`.\n\nFor development (linting, packaging,...) there are a few more dependencies which can be installed via:\n\n`pip install -r requirements_dev.txt`.\n\n### System Requirements\n\nThe initial cloning of the `llvm-project` repo will take a long time, hence a good internet connection is recommended. To run the demo, make sure to have at least 20GB (>40GB for debug builds) of disk space available in the destination (`/tmp/seal5_llvm_demo`) directory. The target directory can be changed as follows: `DEST=$HOME/seal5_demo`.\n\n### Installation\n\n**Warning:** It is highly recommended to install `seal5` into a new virtual environment. Follow these steps to initialize and enter a venv in your seal5 repo directory:\n\n```sh\n# alternative: python3 -m venv venv\nvirtualenv -p python3.8 venv\nsource venv/bin/activate\n```\n\n#### From PyPI\n\n```\npip install seal5\n```\n\n#### Local Development Version\n\nFirst prepare your shell by executing `export PYTHONPATH=$(pwd):$PYTHONPATH` inside the seal5 repository. Then you should be able to use Seal5 without needing to reinstall it.\n\nAlternatively you should be able to use `pip install -e .`.\n\n## Usage\n\n### Python API\n\nThe flow can be sketched as follows (see Example below for functional code!):\n\n```python\n# Create flow\nseal5_flow = Seal5Flow(...)\n# Initialize LLVM repo and .seal5 directories\nseal5_flow.initialize(...)\n# Optional: remove artifacts from previous builds\nseal5_flow.reset(...)\n# Install Seal5 dependencies (CDSL2LLVM/PatternGen)\nseal5_flow.setup(...)\n# Load CoreDSL2+CFG files (Git config, filters,...)\nseal5_flow.load(...)\n# Transform Seal5 model (Extract side effects, operands,...)\nseal5_flow.transform(...)\n# Generate patches based on Seal5 model (ISel patterns, RISC-V features,...)\nseal5_flow.generate(...)\n# Apply generated (and manual) patches to LLVM codebase\nseal5_flow.patch(...)\n# Build patches LLVM (This will take a while)\nseal5_flow.build(...)\n# Run LLVM+Seal5 tests to verify functionality\nseal5_flow.test(...)\n# Combine patches and install LLVM\nseal5_flow.deploy(...)\n# Archive final LLVM (optionally inclusing logs, reports,...)\nseal5_flow.export(...)\n# Optional: Cleanup all artifacts\nseal5_flow.cleanup(...)\n```\n\n### Command-Line Interface\n\nCommand line interface is aligned with the Python API. See `examples/demo.sh` for an full usage example\n\n```sh\nexport SEAL5_HOME=...\nseal5 --dir $SEAL5_HOME reset --settings\nseal5 init [--non-interactive] [-c]\nseal5 load --files ...\nseal5 setup ...\nseal5 transform ...\nseal5 generate ...\nseal5 patch ...\nseal5 build ...\nseal5 test ...\nseal5 deploy ...\nseal5 export ...\nseal5 clean [--temp] [--patches] [--models] [--inputs]\n```\n\n## Examples\n\nSee [`examples/demo.py`](https://github.com/tum-ei-eda/seal5/blob/main/examples/demo.py) for example of end-to-end flow!\n\n## Documentation\n\nCheckout [Seal5's ReadTheDocs Page](https://seal5.readthedocs.io/en/latest/?version=latest)!\n\n## Limitations\n\nSee [here](https://github.com/tum-ei-eda/seal5/blob/main/LIMITATIONS.md).\n\n## CI/CD Flow\n\nWe added a (manual) CI job to run the `examples/demo.py` script via GitHub actions.\n\n## Contributions\n\nSeal5 issue tracker: https://github.com/tum-ei-eda/seal5/issues\n\nCoreDSL2LLVM/PatternGen issue tracker: https://github.com/mathis-s/CoreDSL2LLVM/issues\n\n## References\n\nN/A\n\n## Acknowledgment\n\n<img src=\"./BMBF_gefoerdert_2017_en.jpg\" alt=\"drawing\" height=\"75\" align=\"left\" >\n\nThis research is partially funded by the German Federal Ministry of Education and Research (BMBF) within\nthe projects [Scale4Edge](https://www.edacentrum.de/scale4edge/) (grant number 16ME0465) and [MANNHEIM-FlexKI](https://www.edacentrum.de/projekte/MANNHEIM-FlexKI) (grant number 01IS22086L).\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Seal5 - Semi-automated LLVM Support for RISC-V Extensions including Autovectorization",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/tum-ei-eda/seal5"
},
"split_keywords": [
"seal5"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "230f9d8f3d6a198479d5bfeb21a83fbcf5d63d7ce61071fc3e802b486af45357",
"md5": "5b458cf098f80b7385f367946edfac63",
"sha256": "ec094fc37690d6844219bcc693d09fe31dfb1c35938b7b6dc0c9f283b658601e"
},
"downloads": -1,
"filename": "seal5-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b458cf098f80b7385f367946edfac63",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 178370,
"upload_time": "2024-10-31T08:21:08",
"upload_time_iso_8601": "2024-10-31T08:21:08.804446Z",
"url": "https://files.pythonhosted.org/packages/23/0f/9d8f3d6a198479d5bfeb21a83fbcf5d63d7ce61071fc3e802b486af45357/seal5-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "abcf629d9838515d4a414fac8d5f43c86c197d6f9e9aa9d3c93da98153aeca27",
"md5": "51c46661cf1f4df30fd7b1fd8adfe6f6",
"sha256": "59da5e0a2e72aee2f42daa6607ca151d6e653782b7e183688483d033d01bbb5b"
},
"downloads": -1,
"filename": "seal5-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "51c46661cf1f4df30fd7b1fd8adfe6f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 90772,
"upload_time": "2024-10-31T08:21:09",
"upload_time_iso_8601": "2024-10-31T08:21:09.985944Z",
"url": "https://files.pythonhosted.org/packages/ab/cf/629d9838515d4a414fac8d5f43c86c197d6f9e9aa9d3c93da98153aeca27/seal5-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-31 08:21:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tum-ei-eda",
"github_project": "seal5",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "gitpython",
"specs": []
},
{
"name": "pyyaml",
"specs": []
},
{
"name": "m2isar",
"specs": []
},
{
"name": "importlib_resources",
"specs": []
},
{
"name": "dacite",
"specs": []
},
{
"name": "mako",
"specs": []
},
{
"name": "tqdm",
"specs": []
}
],
"lcname": "seal5"
}
JSON
