{"id":13744859,"url":"https://github.com/bu-icsg/dana","last_synced_at":"2025-05-09T04:30:59.914Z","repository":{"id":78217862,"uuid":"52231381","full_name":"bu-icsg/dana","owner":"bu-icsg","description":"Dynamically Allocated Neural Network Accelerator for the RISC-V Rocket Microprocessor in Chisel","archived":false,"fork":false,"pushed_at":"2020-01-23T13:33:23.000Z","size":1900,"stargazers_count":205,"open_issues_count":24,"forks_count":36,"subscribers_count":31,"default_branch":"master","last_synced_at":"2024-08-04T05:05:04.796Z","etag":null,"topics":["chisel","hardware","neural-network","riscv","rocc","rocket-chip","rtl"],"latest_commit_sha":null,"homepage":"","language":"Scala","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/bu-icsg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.BU","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-02-21T22:25:45.000Z","updated_at":"2024-07-18T01:11:47.000Z","dependencies_parsed_at":"2023-04-26T23:00:22.204Z","dependency_job_id":null,"html_url":"https://github.com/bu-icsg/dana","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bu-icsg%2Fdana","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bu-icsg%2Fdana/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bu-icsg%2Fdana/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bu-icsg%2Fdana/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bu-icsg","download_url":"https://codeload.github.com/bu-icsg/dana/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224811271,"owners_count":17373934,"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":["chisel","hardware","neural-network","riscv","rocc","rocket-chip","rtl"],"created_at":"2024-08-03T05:01:17.402Z","updated_at":"2024-11-15T16:32:04.273Z","avatar_url":"https://github.com/bu-icsg.png","language":"Scala","funding_links":[],"categories":["Scala","Open Source Implementations"],"sub_categories":["Accelerators"],"readme":"Dynamically Allocated Neural Network (DANA) Accelerator\n========================================\n\nA [Chisel3](https://github.com/ucb-bar/chisel3) implementation of a fully connected neural network accelerator, DANA, supporting inference or learning. DANA follows a transactional model of computation supporting simultaneous multithreading of transactions [[1]](#cite-pact2015).\nDANA integrates with the [RISC-V Rocket microprocessor](https://github.com/ucb-bar/rocket-chip) as a Rocket Custom Coprocessor (RoCC).\n\nThis is currently compatibile with [rocket-chip:f3299ae9](https://github.com/ucb-bar/rocket-chip/commit/f3299ae91d3f01d0349eb4746886e303e8fb1b41) -- an older rocket-chip version used by fpga-zynq.\n\n### tl;dr: Setup\n\nThis is compatible with [ucb-bar/fpga-zynq:f03982e](https://github.com/ucb-bar/fpga-zynq/commit/f03982e6a155d333b3b3708185898745df5d4004). Clone this repo, add DANA, and build:\n\n```bash\n# Clone fpga-zynq\ngit clone https://github.com/ucb-bar/fpga-zynq $fpga_zynq_dir\ncd $fpga_zynq_dir\ngit reset --hard f03982e\ngit submodule update --init rocket-chip testchipip\n\n# Add DANA to rocket-chip\ncd $fpga_zynq_dir/rocket-chip\ngit submodule update --init\ngit clone https://github.com/bu-icsg/dana\ncd $fpga_zynq_dir/rocket-chip/dana\ngit submodule update --init\n\n# Build an emulator\ncd $fpga_zynq_dir/rocket-chip/emulator\nmake ROCKETCHIP_ADDONS=dana CONFIG=DanaEmulatorConfig\n\n# Build example DANA networks in 'dana/build/nets'\ncd $fpga_zynq_dir/rocket-chip/dana\nmake\n\n# Build bare metal tests for DANA in 'dana/tests/build'\ncd $fpga_zynq_dir/rocket-chip/riscv-tools\ngit submodule update --init --recursive riscv-tests\ncd $fpga_zynq_dir/rocket-chip/dana/tests\nautoconf\nmkdir build\ncd build\n../configure\nmake\n\n# Run tests on the emulator with or without printfs\ncd $fpga_zynq_dir/rocket-chip/emulator\n./emulator-rocketchip-DanaEmulatorConfig \\\n  ../dana/tests/build/nets/xfiles-dana-nets-p-xorSigmoidSymmetric\n./emulator-rocketchip-DanaEmulatorConfig \\\n  +verbose \\\n  ../dana/tests/build/nets/xfiles-dana-nets-p-xorSigmoidSymmetric \\\n  2\u003e\u00261 | \\\n  spike-dasm | \\\n  tee xfiles-dana-nets-p-xorSigmoidSymmetric.log\n```\n\nTo build Verilog suitable for Zynq FPGAs (Zedboard, ZC706):\n\n```bash\n# Add a Zedboard configuration to fpga-zynq\necho \"class DanaZedboardConfig extends Config (\n  new rocketchip.HasDanaRocc ++\n  new xfiles.DefaultXFilesConfig ++\n  new dana.DanaConfig(\n    numPes     = 2,\n    cache      = 1,\n    cacheSize  = 512 * 1024,\n    scratchpad =  16 * 1024) ++\n    new dana.DefaultDanaConfig ++\n    new ZynqConfig)\" \u003e\u003e $fpga_zynq_dir/common/src/main/scala/Configs.scala\n\n# Build for the FPGA (Zedboard)\ncd $fpga_zynq_dir/zedboard\nmake rocket ROCKETCHIP_ADDONS=dana CONFIG=DanaZedboardConfig\nmake project ROCKETCHIP_ADDONS=dana CONFIG=DanaZedboardConfig\nmake fpga-images-zedboard/boot.bin CONFIG=DanaZedboardConfig\n```\n\n### \u003ca name=\"toc\"\u003e\u003c/a\u003e Table of Contents\n- [Setup](#setup)\n    - [1 - Clone the Rocket Chip Repository](#clone-the-rocket-chip-repo)\n    - [2 - Build a RISC-V Toolchain](#riscv-toolchain)\n- [Software Emulation](#emulation)\n    - [Rocket + DANA Emulation](#emulation-rocket-chip)\n    - [Debugging](#emulation-debugging)\n        - [Printf Debugging](#printf-debugging)\n        - [Waveform Debugging](#waveform-debugging)\n- [Hardware Evaluation](#hardware)\n    - [FPGA Target](#fpga-target)\n        - [1 - Verilog Generation](#verilog-generation)\n        - [2 - Create a Vivado Project](#vivado-project)\n        - [3 - Generate Zynq Configuration](#boot-bin)\n        - [4 - Load the SD Card](#load-sd-card)\n        - [5 - Test on the FPGA](#test-on-the-fpga)\n- [Known Issues, WIP Features](#known-issues)\n    - [Configuration Size](#configuration-size)\n    - [Linux Support](#linux-support)\n    - [IO Queues](#io-queues)\n- [Additional Documentation](#documentation)\n    - [Attribution](#attribution)\n    - [Doc Directory](#doc-directory)\n    - [Publications](#publications)\n    - [Workshop Presentations and Posters](#presentations-posters)\n- [Contributors and Acknowledgments](#contributors-acknowledgments)\n\n### \u003ca name=\"setup\"\u003e\u003c/a\u003e Setup\n\nRequirements:\n* `python 3.X`\n* `numpy`\n* `scipy`\n* All dependencies needed for the [RISC-V toolchain](https://www.github.com/riscv/riscv-tools)\n\n1) \u003ca name=\"clone-the-rocket-chip-repo\"\u003e\u003c/a\u003e Clone the Rocket Chip Repository\n----------------------------------------\nThis is not, at present, a standalone repository and must be cloned inside of an existing Rocket Chip clone. The following will grab a supported version of rocket-chip and clone DANA inside of it:\n\n```\ngit clone https://github.com/ucb-bar/rocket-chip $ROCKETCHIP_DIR\ncd $ROCKETCHIP_DIR\ngit reset --hard f3299ae91d3f01d0349eb4746886e303e8fb1b41\ngit submodule update --init --recursive\ngit clone https://github.com/bu-icsg/dana\ncd dana\ngit submodule update --init\n```\n\n2) \u003ca name=\"riscv-toolchain\"\u003e\u003c/a\u003e Build the RISC-V Toolchain\n----------------------------------------\nThis requires a supported version of the RISC-V toolchain. Go ahead and build the version of the toolchain pointed at by the rocket-chip repository. This requires setting the `RISCV` environment variable and satisfying any dependencies required to build the toolchain.\n\n```\ncd $ROCKETCHIP_DIR/riscv-tools\n./build.sh\n```\n\n### \u003ca name=\"emulation\"\u003e\u003c/a\u003e Emulation (Functional Verification)\nThis project uses [Chisel3](https://github.com/ucb-bar/chisel3) and [FIRRTL](https://github.com/ucb-barc/firrtl) for hardware design and Verilog generation.\n\n#### \u003ca name=\"emulation-rocket-chip\"\u003e\u003c/a\u003e Rocket Chip Emulation\nYou can build a complete version of Rocket Chip that includes DANA in a RoCC socket.\n\nYou can build an emulator of Rocket + DANA using the rocket-chip make target inside the rocket-chip/emulator directory. The Makefile just needs to know what configuration we're using and that we have additional Chisel code located in the `dana` directory:\n```bash\ncd $ROCKETCHIP/emulator\nmake CONFIG=DanaEmulatorConfig ROCKETCHIP_ADDONS=dana\n```\n\nWe provide bare-metal test programs inside the [tests](tests) directory.\n\n#### \u003ca name=\"emulation-debugging\"\u003e\u003c/a\u003e Emulation Debugging\n\nFor debugging or running the emulator more verbosely, you have the option of either relying on Chisel's `printf` or building a version of the emulator that supports full VCD dumping.\n\n##### \u003ca name=\"printf-debugging\"\u003e\u003c/a\u003e Printf Debugging\n\nChisel's `printf` writes to STDERR, all `printf` statements are disabled by default. You can enable all Chisel-included `printf` commands with the `+verbose` option:\n\n```\ncd $ROCKETCHIP/emulator\n./emulator-Top-DanaEmulatorConfig +verbose [binary] 2\u003e\u00261 | tee run.log\n```\n\nNote: Rocket Chip dumps information every cycle and it is often useful to grep for the exact `printf` that you're looking for.\n\n##### \u003ca name=\"waveform-debugging\"\u003e\u003c/a\u003e Waveform Debugging\n\nYou can build a \"debug\" version of the emulator (which provides full support for generating vcd traces  with:\n```\ncd $ROCKETCHIP/emulator\nmake debug\n```\n\nThis creates a `*-debug` emulator which supports a `-v[FILE]` option for generating a VCD file, a `+start` option for starting VCD dumping at a specific cycle.\n\nTo further reduce the size of the VCD file we provide a tool that prunes a VCD file to only include signals in a specific module and it's children, [`vcd-prune`](https://github.com/IBM/hdl-tools/blob/master/scripts/vcd-prune). Example usage to only emit DANA signals:\n\n```\ncd $ROCKETCHIP_DIR/emulator\n./emulator-Top-DanaEmulatorConfig-debug -v- [binary] 2\u003e\u00261 | ../dana/util/hdl-tools/scripts/vcd-prune -m Dana \u003e run.vcd\n```\n\nThis waveform can then be viewed using GTKWave by building GTKWave locally and using a helper script to pre-populate the waveform window:\n\n```\ncd $ROCKETCHIP/emulator\nmake -C ../dana/util/hdl-tools gtkwave\n../dana/util/hdl-tools/scripts/gtkwave-helper run.vcd\n```\n\n### \u003ca name=\"hardware\"\u003e\u003c/a\u003e Hardware Evaluation\n\nRocket + DANA can be evaluated on a Zynq FPGA using the Berkeley-provided [`fpga-zynq`](https://github.com/ucb-bar/fpga-zynq) repository.\n\n### \u003ca name=\"known-issues\"\u003e\u003c/a\u003e Known Issues and WIP Features\nThere are a few remaining things that we're working on closing out which limit the set of available features.\n\n#### \u003ca name=\"configuration-size\"\u003e\u003c/a\u003e Configuration Size\nCurrently, the neural network configuration must fit completely in one of DANA's configuration cache memories. DANA's neural network configuration format using 32-bit internal pointers meaning that networks up to 4GiB are theoretically supported. We've used networks up to 512KiB in size on FPGA without issue.\n\n#### \u003ca name=\"linux-support\"\u003e\u003c/a\u003e Linux Support\nWe're working on a full integration of the X-FILES supervisor library with the Linux kernel. Supervisor features are currently supported via system calls added to the [RISC-V Proxy Kernel](https://www.github.com/riscv/riscv-pk) via an included [patch](patches/riscv-pk-xfiles-syscalls.patch).\n\n#### \u003ca name=\"io-queues\"\u003e\u003c/a\u003e IO Queues\nWhile neural network configurations are loaded from the memory of the microprocessor, all input and output data is transferred from Rocket to DANA hardware through the Rocket Custom Coprocessor (RoCC) register interface. We have plans to enable asynchronous transfer through in-memory queues.\n\n### \u003ca name=\"documentation\"\u003e\u003c/a\u003e Additional Documentation\n\nAdditional documentation can be found in the [`doc`](doc) directory or in some of our publications.\n\n#### \u003ca name=\"attribution\"\u003e\u003c/a\u003e Attribution\nIf you use this for research, please cite the original PACT paper:\n```\n@inproceedings{eldridge2015,\n  author    = {Schuyler Eldridge and\n               Amos Waterland and\n               Margo Seltzer and\n               Jonathan Appavoo and\n               Ajay Joshi},\n  title     = {Towards General-Purpose Neural Network Computing},\n  booktitle = {2015 International Conference on Parallel Architecture and Compilation,\n               {PACT} 2015, San Francisco, CA, USA, October 18-21, 2015},\n  pages     = {99--112},\n  year      = {2015},\n  url       = {http://dx.doi.org/10.1109/PACT.2015.21},\n  doi       = {10.1109/PACT.2015.21},\n  timestamp = {Wed, 04 May 2016 14:25:23 +0200},\n  biburl    = {http://dblp.uni-trier.de/rec/bib/conf/IEEEpact/EldridgeWSAJ15},\n  bibsource = {dblp computer science bibliography, http://dblp.org}\n}\n```\n\n#### \u003ca name=\"doc-directory\"\u003e\u003c/a\u003e Doc Directory\nSpecific documentation includes:\n* [Binary Encodings and Data Structures](doc/binary-encodings-data-structures.md)\n* [Debugging](doc/debugging.md)\n* [FPGA Setup](doc/fpga-setup.md)\n* [Timing](doc/timing.md)\n* [Toolflow](doc/toolflow.md)\n* [U-Boot](doc/u-boot.md)\n\n#### \u003ca name=\"publications\"\u003e\u003c/a\u003e Publications\n\u003ca name=\"cite-pact2015\"\u003e\u003c/a\u003e [1] S. Eldridge, A. Waterland, M. Seltzer, J. Appavoo, and A. Joshi, \"Towards General Purpose Neural Network Computing\", _in Proceedings of the International Conference on Parallel Architectures and Compilation Techniques (PACT)_. 2015.\n* [Paper](http://people.bu.edu/schuye/files/pact2015-eldridge-paper.pdf)\n* [Presentation](http://people.bu.edu/schuye/files/pact2015-eldridge-presentation.pdf)\n\n\u003ca name=\"cite-thesis\"\u003e\u003c/a\u003e [2] S. Eldridge, \"Neural Network Computing Using On-Chip Accelerators\", Boston University. 2016.\n* [Thesis](http://people.bu.edu/joshi/files/thesis-eldridge.pdf)\n\n#### \u003ca name=\"presentations-posters\"\u003e\u003c/a\u003e Workshop Presentations and Posters\n[3] S. Eldridge., T. Unger, M. Sahaya Louis, A. Waterland, M. Seltzer, J. Appavoo, and A. Joshi, \"Neural Networks as Function Primitives: Software/Hardware Support with X-FILES/DANA\", _Boston Area Architecture Workshop (BARC)_. 2016.\n* [Paper](http://people.bu.edu/schuye/files/barc2016-eldridge-paper.pdf)\n* [Presentation](http://people.bu.edu/schuye/files/barc2016-eldridge-presentation.pdf)\n* [Poster](http://people.bu.edu/schuye/files/barc2016-eldridge-poster.pdf)\n\n### \u003ca name=\"contributors-acknowledgments\"\u003e\u003c/a\u003e Contributors and Acknowledgments\nThe following people, while not mentioned in the commit log, have contributed directly or indirectly to the development of this work:\n* [Jonathan Appavoo](http://www.cs.bu.edu/~jappavoo/jappavoo.github.com/index.html)\n* [Amos Waterland](http://people.seas.harvard.edu/~apw/)\n* [Tommy Unger](http://www.cs.bu.edu/~jappavoo/jappavoo.github.com/index.html)\n* [Han Dong](http://cs-people.bu.edu/handong/)\n* [Leila Delshad Tehrani](http:/www.bu.edu/icsg)\n\nThis work was funded by a NASA Space Technology Research Fellowship.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbu-icsg%2Fdana","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbu-icsg%2Fdana","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbu-icsg%2Fdana/lists"}