{"id":13773203,"url":"https://github.com/pnnl/soda-opt","last_synced_at":"2025-04-12T05:13:05.978Z","repository":{"id":184484827,"uuid":"671743959","full_name":"pnnl/soda-opt","owner":"pnnl","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-17T17:53:21.000Z","size":8060,"stargazers_count":44,"open_issues_count":9,"forks_count":10,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-12T05:12:55.143Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pnnl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-28T03:21:06.000Z","updated_at":"2025-04-12T04:58:50.000Z","dependencies_parsed_at":"2024-06-28T17:17:33.961Z","dependency_job_id":"a4987fe6-be25-4dda-b868-33e604849331","html_url":"https://github.com/pnnl/soda-opt","commit_stats":null,"previous_names":["pnnl/soda-opt"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnnl%2Fsoda-opt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnnl%2Fsoda-opt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnnl%2Fsoda-opt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnnl%2Fsoda-opt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pnnl","download_url":"https://codeload.github.com/pnnl/soda-opt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248519556,"owners_count":21117761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T17:01:12.702Z","updated_at":"2025-04-12T05:13:05.950Z","avatar_url":"https://github.com/pnnl.png","language":"C++","funding_links":[],"categories":["Circuit Compilers"],"sub_categories":[],"readme":"[![Build and Test](https://github.com/pnnl/soda-opt/actions/workflows/buildAndTest.yml/badge.svg)](https://github.com/pnnl/soda-opt/actions/workflows/buildAndTest.yml)\n[![License](https://img.shields.io/badge/License-BSD_2--Clause-orange.svg)](https://github.com/pnnl/soda-opt/blob/main/LICENSE.txt)\n\n# SODA-OPT - Enabling System Level Design in MLIR\n\nThis project aims to create `soda-opt`, a tool that leverages `mlir` to extract, \noptimize, and translate high-level code snippets into LLVM IR, \nso that they can be synthesized by our high-level synthesis tool of choice.\n\nAs a long term vision, the SODA-OPT project seeks to provide a set of\n*compiler libraries* to perform the target optimizations; *runtime libraries* \nto offload the compute from host to the selected targets; and to be\n*standalone*, being built on top of standard `mlir` tools and dialects, so\nthat any project (e.i. TF, ONNX, etc) could use the exposed optimization\npasses to offload and perform HLS of selected code snippets. As a final\ngoal, `soda-opt` could later be merged into the main `llvm-project` codebase.\n\n\n## Getting started\n\nPull our production image on dockerhub:\n\n- https://hub.docker.com/r/agostini01/soda\n\nAnd follow one of our tutorials [here](docs/tutorials).\n\n\n## How to build?\n\nThis setup assumes that you have built LLVM and MLIR in `$BUILD_DIR` and\ninstalled it to `$PREFIX`. \nThe current version of this project was tested with `llvm-project` commit:\n`339a7687e1c036a5f91c9d5391523b93e2e76cd3`.\nMake sure you have the correct commit checked-out.\n\n**Note**: Make sure to pass `-DLLVM_INSTALL_UTILS=ON` when building LLVM/MLIR \nwith CMake so that it installs `FileCheck`.\n\nTo build `soda-opt` and run the tests of this project, execute:\n\n```sh\nmkdir build \u0026\u0026 cd build\ncmake -G Ninja .. \\\n    -DLLVM_EXTERNAL_LIT=$BUILD_DIR/bin/llvm-lit \\\n    -DMLIR_DIR=$PREFIX/lib/cmake/mlir\n\n# Run tests\ncmake --build . --target check-soda\n```\n\n### Building LLVM/MLIR with Helper Script\n\nLLVM can be built with the helper `build_tools/build_llvm.sh`.\n\n```sh\n# To configure, build, and install\n./build_llvm.sh \u003cpath/to/llvm/src\u003e \u003cllvm_build_dir\u003e \u003cllvm_install_dir\u003e\n```\n\n### Building soda-opt with Helper Script\n\nAlternatively it is possible to use the helper script\n`build_tools/build_soda.sh` to build this project:\n\n```sh\n# To configure, build, and install\n./build_tools/build_soda.sh \u003csource_dir\u003e \u003cinstall_dir\u003e \u003cbuild_dir\u003e \u003cpath/to/llvm/build/dir\u003e \u003cpath/to/llvm/install/dir\u003e\n```\n\n## How to generate the docs?\n\nTo build the documentation from the TableGen description of the dialect\noperations, run:\n```sh\ncmake --build . --target mlir-doc\n```\n\n## How to use this project?\n\nAfter successful build, available passes can be displayed with:\n\n```sh\n$PROJ_BUILD_DIR/bin/soda-opt -h\n```\n\nThe passes and pipelines described below have several options,\ncheck `soda-opt -h` for additional informaton.\n\n\nSearch passes can be executed with the following command:\n\n```sh\n$PROJ_BUILD_DIR/bin/soda-opt \\\n  $PROJ_ROOT_DIR/test/soda-opt/linalg-matmul.mlir \\\n  --convert-linalg-matmul-to-soda\n\n# Other patterns can be marked for outlining with passes following the\n# template:\n# --convert-\u003cdialect_name\u003e-\u003cop_name\u003e-to-soda\n```\n\nKernel outlining pass can be executed with the following command:\n\n```sh\n$PROJ_BUILD_DIR/bin/soda-opt \\\n  $PROJ_ROOT_DIR/test/Dialect/SODA/outlining-matmul.mlir \\\n  --soda-outline-bambu-code\n\n# In the future, searched coded can be outlined for other architectures\n# following the pass template: \n# --soda-outline-\u003ctarget_name\u003e-code\n```\n\nThe above command can include automatic XML test generation to be\nlater used during simulation:\n\n```sh\n$PROJ_BUILD_DIR/bin/soda-opt \\\n  $PROJ_ROOT_DIR/test/Dialect/SODA/outlining-matmul.mlir \\\n  --soda-outline-bambu-code \\\n  --soda-extract-arguments-to-xml=using-bare-ptr\n# This will generate an xml file for each outlined kernel in the\n# folder in which was called\n```\n\nGeneration/extraction of kernel code exclusive for bambu can be obtained with\nthe following command:\n\n```sh\n$PROJ_BUILD_DIR/bin/soda-opt \\\n  $PROJ_ROOT_DIR/test/Dialect/SODA/outlining-matmul.mlir \\\n  --soda-generate-bambu-accelcode\n\n# In the future, outlined code can be extracted for other target architectures\n# following the pass template:\n# --soda-generate-\u003ctarget_name\u003e-accelcode\n```\n\nGeneration of host code calls to the target accelerator api can be obtained\nwith the following command:\n\n```sh\n# Note this is still under development\n$PROJ_BUILD_DIR/bin/soda-opt \\\n  $PROJ_ROOT_DIR/test/Dialect/SODA/outlining-matmul.mlir \\\n  --soda-generate-bambu-hostcode\n\n# In the future, additional host code generation for other accelerator APIs\n# will be generated by the following pass template:\n# --soda-generate-\u003ctarget_name\u003e-hostcode\n```\n\nOptimizations passes and lowerings can be executed on a `.mlir` file with the\nfollowing command:\n\n```sh\n# Simply lower all operations to the llvm dialect\n$PROJ_BUILD_DIR/bin/soda-opt \\\n  $PROJ_ROOT_DIR/test/soda-opt/linalg-matmul.mlir \\\n  --lower-all-to-llvm\n\n# Perform loop tiling to fit 512KiB \"L1\" memory\n$PROJ_BUILD_DIR/bin/soda-opt \\\n  $PROJ_ROOT_DIR/test/soda-opt/linalg-matmul.mlir \\\n  --soda-opt-pipeline=\"cache-size=512\"\n\n# Specfic pipeline for bambu (with bare pointer call convertion)\n$PROJ_BUILD_DIR/bin/soda-opt \\\n  $PROJ_ROOT_DIR/test/soda-opt/linalg-matmul.mlir \\\n  --soda-opt-pipeline-for-bambu=use-bare-ptr-memref-call-conv\n\n# Check other options in the -soda-opt-pipeline-for-bambu with\n$PROJ_BUILD_DIR/bin/soda-opt -h | less\n\n# In the future, additional pipelines for other target architectures\n# will be executed by the following pass template:\n # --soda-opt-pipeline-for-\u003ctarget_name\u003e\n```\n\nTo use python bindings, setup python lib path:\n\n```\nexport PYTHONPATH=$PYTHONPATH:$MLIR_BUILD_DIR/tools/mlir/python_packages/mlir_core\nexport PYTHONPATH=$PYTHONPATH:$PROJ_BUILD_DIR/python_packages/soda\n```\n\nImport soda libraries like this:\n\n```python\nfrom mlir_soda.ir import *\nfrom mlir_soda.dialects import (\n  builtin as builtin_d,\n  soda as soda_d\n)\n```\n\n## Credits\n\nThis project was build on top of the mlir out-of-tree template available here:\n\n- Original author: https://github.com/jmgorius/mlir-standalone-template\n- LLVM Mirror: https://github.com/llvm/llvm-project/tree/main/mlir/examples/standalone\n\n---\n\n## License\n\nThis project is made available under the BSD2 License.  See the\n[LICENSE.txt](LICENSE.txt) file for more details.\n\n### Software from third parties included in the SODA-OPT Project\n\nThe SODA-OPT Project contains third party software which is under different\nlicense terms. All such code will be identified clearly using at least one of\ntwo mechanisms:\n1) It will be in a separate directory tree with its own `LICENSE.txt` or\n   `LICENSE` file at the top containing the specific license and restrictions\n   which apply to that software, or\n2) It will contain specific license and restriction terms at the top of every\n   file. \n\n---\n\n# Publications\n\n- [ICCAD 2022](https://dl.acm.org/doi/abs/10.1145/3508352.3549424)\n- [IEEE Micro 2022](https://ieeexplore.ieee.org/abstract/document/9786533)\n\n```\n@inproceedings{10.1145/3508352.3549424,\n  author = {Bohm Agostini, Nicolas and Curzel, Serena and Amatya, Vinay and Tan, Cheng and Minutoli, Marco and Castellana, Vito Giovanni and Manzano, Joseph and Kaeli, David and Tumeo, Antonino},\n  title = {An MLIR-Based Compiler Flow for System-Level Design and Hardware Acceleration},\n  year = {2022},\n  isbn = {9781450392174},\n  publisher = {Association for Computing Machinery},\n  address = {New York, NY, USA},\n  doi = {10.1145/3508352.3549424},\n  booktitle = {Proceedings of the 41st IEEE/ACM International Conference on Computer-Aided Design},\n  articleno = {6},\n  numpages = {9},\n  keywords = {high-level optimizations, compilers, MLIR, HLS},\n  location = {San Diego, California},\n  series = {ICCAD '22}\n}\n\n@ARTICLE{9786533,\n  author={Bohm Agostini, Nicolas and Curzel, Serena and Zhang, Jeff and Limaye, Ankur and Tan, Cheng and Amatya, Vinay and Minutoli, Marco and Castellana, Vito Giovanni and Manzano, Joseph and Brooks, David and Wei, Gu-Yeon and Tumeo, Antonino},\n  journal={IEEE Micro}, \n  title={Bridging Python to Silicon: The SODA Toolchain}, \n  year={2022},\n  doi={10.1109/MM.2022.3178580}}\n```\n\n---\n\n# Disclaimer Notice\n\nThis material was prepared as an account of work sponsored by an agency of the\nUnited States Government.  Neither the United States Government nor the United\nStates Department of Energy, nor Battelle, nor any of their employees, nor any\njurisdiction or organization that has cooperated in the development of these\nmaterials, makes any warranty, express or implied, or assumes any legal\nliability or responsibility for the accuracy, completeness, or usefulness or any\ninformation, apparatus, product, software, or process disclosed, or represents\nthat its use would not infringe privately owned rights.\n\nReference herein to any specific commercial product, process, or service by\ntrade name, trademark, manufacturer, or otherwise does not necessarily\nconstitute or imply its endorsement, recommendation, or favoring by the United\nStates Government or any agency thereof, or Battelle Memorial Institute. The\nviews and opinions of authors expressed herein do not necessarily state or\nreflect those of the United States Government or any agency thereof.\n\n\u003cdiv align=center\u003e\n\u003cpre style=\"align-text:center\"\u003e\nPACIFIC NORTHWEST NATIONAL LABORATORY\noperated by\nBATTELLE\nfor the\nUNITED STATES DEPARTMENT OF ENERGY\nunder Contract DE-AC05-76RL01830\n\u003c/pre\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpnnl%2Fsoda-opt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpnnl%2Fsoda-opt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpnnl%2Fsoda-opt/lists"}