OPEN: Minor CI and Readme Improvements (#8)

* Fix Docker container link

* Retry long tests if they timeout

* Automatically runs the CI every 6 days to keep the cache fresh

* Update README, changelog, contributing.md, and add PR template

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -0,0 +1,17 @@
+Describe the intent of your PR here.
+
+## Added
+- 
+
+## Changed
+- 
+
+## Fixed
+- 
+
+## PR Merge Checklist
+
+1. [ ] The PR is rebased on the latest `devel` commit and pointing to `devel`.
+2. [ ] Your PR reviewed and approved.
+3. [ ] All checks are passing.
+4. [ ] The `CHANGELOG.md` file has been updated.

.github/workflows/BuildDocker.yml

@@ -37,4 +37,5 @@ jobs:
           context: .
           file: Container/Dockerfile
           push: true
-          tags: ghcr.io/pulp-platform/deeploy:main
+          # JUNGVI: If you operate from a fork and want to build a new docker make sure to replace 'pulp-platform' by your uname. 
+          tags: ghcr.io/pulp-platform/deeploy:main 

.github/workflows/CI.yml

@@ -4,13 +4,16 @@ on:
   push:
   pull_request:
   workflow_dispatch:
+  schedule:
+    # Runs the CI on the default branch every 6 days at 2AM CET to keep the cache fresh
+    - cron: "0 1 */6 * *"
 
 jobs:
 
   build-deeploy:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4
@@ -496,7 +499,7 @@ jobs:
   deeploy-state-serialization:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4
@@ -516,7 +519,7 @@ jobs:
   deeploy-memory-level-extension:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4
@@ -536,7 +539,7 @@ jobs:
   deeploy-tiler-extension:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4
@@ -560,7 +563,7 @@ jobs:
   deeploy-memory-allocation-extension:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4
@@ -582,7 +585,7 @@ jobs:
   deeploy-typing:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4
@@ -599,7 +602,7 @@ jobs:
   deeploy-regex-matching:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4
@@ -616,7 +619,7 @@ jobs:
   linting:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4
@@ -651,7 +654,3 @@ jobs:
         run: |
           grep -Lr "SPDX-License-Identifier: Apache-2.0" --exclude-dir="toolchain" --exclude-dir="install" --exclude-dir=".git" . --exclude-dir="third_party" --exclude-dir="TEST_*" --exclude-dir="runtime" | grep ".*\.h$" || [[ $? == 1 ]]
         shell: bash
-
-
-
-

.github/workflows/TestRunnerCortexM.yml

@@ -11,7 +11,7 @@ jobs:
   test-runner-cortexm:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4

.github/workflows/TestRunnerGeneric.yml

@@ -11,7 +11,7 @@ jobs:
   test-runner-generic:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4

.github/workflows/TestRunnerMempool.yml

@@ -11,7 +11,7 @@ jobs:
   test-runner-mempool:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4

.github/workflows/TestRunnerSiracusa.yml

@@ -14,7 +14,7 @@ jobs:
   test-runner-siracusa:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4

.github/workflows/TestRunnerTiledSiracusa.yml

@@ -32,7 +32,7 @@ jobs:
         L1: ${{ fromJSON(inputs.L1) }}
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4
@@ -47,11 +47,16 @@ jobs:
           path: /app/.ccache
           key: ${{ runner.os }}-ccache
       - name: Run Test
-        run: |
-          cd DeeployTest
-          mkdir -p /app/.ccache
-          export CCACHE_DIR=/app/.ccache
-          source /app/install/pulp-sdk/configs/siracusa.sh
-          python testRunner_tiled_siracusa.py -t Tests/${{ inputs.test-name }} --cores=${{ inputs.num-cores }} --l1 ${{ matrix.L1 }} --defaultMemLevel=${{ inputs.default-memory-level }} ${{ inputs.double-buffer && '--doublebuffer' || '' }}
-        shell: bash
+        uses: nick-fields/retry@v3
+        with:
+          timeout_minutes: 5
+          max_attempts: 3
+          retry_on: timeout
+          command: |
+            cd DeeployTest
+            mkdir -p /app/.ccache
+            export CCACHE_DIR=/app/.ccache
+            source /app/install/pulp-sdk/configs/siracusa.sh
+            python testRunner_tiled_siracusa.py -t Tests/${{ inputs.test-name }} --cores=${{ inputs.num-cores }} --l1 ${{ matrix.L1 }} --defaultMemLevel=${{ inputs.default-memory-level }} ${{ inputs.double-buffer && '--doublebuffer' || '' }}
+          shell: bash
 

.github/workflows/TestRunnerTiledSiracusaSequential.yml

@@ -24,7 +24,7 @@ jobs:
   test-runner-siracusa-tiled:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4

.github/workflows/TestRunnerTiledSiracusaWithNeureka.yml

@@ -36,7 +36,7 @@ jobs:
         L1: ${{ fromJSON(inputs.L1) }}
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4
@@ -51,11 +51,16 @@ jobs:
           path: /app/.ccache
           key: ${{ runner.os }}-ccache-neureka
       - name: Run Test
-        run: |
-          cd DeeployTest
-          mkdir -p /app/.ccache
-          export CCACHE_DIR=/app/.ccache
-          source /app/install/pulp-sdk/configs/siracusa.sh
-          python testRunner_tiled_siracusa_w_neureka.py -t Tests/${{ inputs.test-name }} --cores=${{ inputs.num-cores }} --l1 ${{ matrix.L1 }} --defaultMemLevel=${{ inputs.default-memory-level }} ${{ inputs.double-buffer && '--doublebuffer' || '' }} ${{ inputs.neureka-wmem && '--neureka-wmem' || '' }}
-        shell: bash
+        uses: nick-fields/retry@v3
+        with:
+          timeout_minutes: 5
+          max_attempts: 3
+          retry_on: timeout
+          command: |
+            cd DeeployTest
+            mkdir -p /app/.ccache
+            export CCACHE_DIR=/app/.ccache
+            source /app/install/pulp-sdk/configs/siracusa.sh
+            python testRunner_tiled_siracusa_w_neureka.py -t Tests/${{ inputs.test-name }} --cores=${{ inputs.num-cores }} --l1 ${{ matrix.L1 }} --defaultMemLevel=${{ inputs.default-memory-level }} ${{ inputs.double-buffer && '--doublebuffer' || '' }} ${{ inputs.neureka-wmem && '--neureka-wmem' || '' }}
+          shell: bash
 

.github/workflows/TestRunnerTiledSiracusaWithNeurekaSequential.yml

@@ -28,7 +28,7 @@ jobs:
   test-runner-siracusa-neureka-tiled:
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/victor-jung/deeploy:main
+      image: ghcr.io/pulp-platform/deeploy:main
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4

CHANGELOG.md

@@ -2,5 +2,16 @@
 
 ## Unreleased
 
+## Fix Generic Softmax Kernel
+
 ### Fixed
 - Fix broken softmax kernel for generic platform ([#2](https://github.com/pulp-platform/Deeploy/pull/2)).
+
+## Minor CI and Readme Improvements
+
+### Added
+- Improved README with more detailed `Getting Started` section, a section listing related publications, and a list of supported platforms.
+- Schedule a CI run every 6 days at 2AM CET to refresh the cache (it expires after 7 days if unused).
+### Fixed
+- Update the link of the Docker container used to run the CI with the Docker published by this repo instead of my fork.
+- Add a retry on timeout step for large network tests. This is a temporary fix to address the sporadic freeze happening at the compilation stage, see [this issue](https://github.com/pulp-platform/Deeploy/issues/9).

CONTRIBUTING.md

@@ -1,35 +1,35 @@
 # Contribution Guide
 
-We encourage submitting your issues and work in merge requests against the devel branch. Please understand that we are trying to maintain a consistent minimal quality standard.
-Any and all merge requests you submit can only be accepted under the Apache 2.0 License.
+We encourage submitting your issues and work in pull requests against the `devel` branch. Please understand that we are trying to maintain a consistent minimal quality standard.
+Any and all pull requests you submit can only be accepted under the Apache 2.0 License.
 
 ## Overview
 
-* The only way new features are accepted are by merge requests against the devel branch. Understand that we expect you to rebase your work against the devel branch if you submit merge requests.
-* We encourage early draft merge requests to keep development transparent and avoid diverging efforts. Please submit your draft merge requests clearly labelled with "DRAFT:".
-* We encourage refactoring. As code evolves, semantic concepts may change, and this is best addressed with refactoring. Please submit merge requests that implement refactoring with a label "REFACTOR:"
-* We strongly encourage discussion on merge requests. Please comment on open merge requests, and keep it productive. The goal is to include feature ideas that are compatible with the Deeploy framework. Feedback for collaborators should include clear actionable items to improve the contribution.
-* If a merge requests addresses a specific feature requests / bug, please reference it in the pull request.
-* Deeploy is a research project. We do not expect a production level workflow, but we ask to add at the very least a proof of concept for any feature implementation. Similarly, if your merge request fixes a bug, please add a regression test for the error condition that was addressed.
+* The only way new features are accepted are by pull requests against the devel branch. We expect you to rebase your work against the devel branch if you submit pull requests.
+* We encourage early draft pull requests to keep development transparent and avoid diverging efforts. Please submit your draft pull requests clearly labelled with "DRAFT:".
+* We encourage refactoring. As code evolves, semantic concepts may change, and this is best addressed with refactoring. Please submit pull requests that implement refactoring with a label "REFACTOR:"
+* We strongly encourage discussion on pull requests. Please comment on open pull requests, and keep it productive. The goal is to include feature ideas that are compatible with the Deeploy framework. Feedback for collaborators should include clear actionable items to improve the contribution.
+* If a pull requests addresses a specific feature requests / bug, please reference it in the description.
+* Deeploy is a research project. We do not expect a production level workflow, but we ask to add at the very least a proof of concept for any feature implementation. Similarly, if your pull request fixes a bug, please add a regression test for the error condition that was addressed.
 
 
 ## Style guide
 
 Deeploy mainly consists of code implemented in C, Makefile, and Python. To facilitate efficient collaboration among users and contributors, it is important to maintain a consistent coding style. To achieve this, it is strongly recommend to use autoformatting tools with the provided configuration files. Additionally, the Continuous Integration (CI) system checks the adherence to the style guide for each pushed commit. Currently configuration for C using `clang-format` and for Python using `yapf` and `isort` are provided.
 
-To recursively format all Python files run
+To recursively format all Python files run:
 ```bash
 $>	autoflake -i -r --remove-all-unused-imports --ignore-init-module-imports --exclude "*/third_party/**" ./
 $>	yapf -ipr -e "third_party/" -e "install/" -e "toolchain/" ./
 $>	isort --sg "**/third_party/*"  --sg "install/*" --sg "toolchain/*" ./
 ```
 
-And for C files
+And for C files:
 ```bash
 $> python scripts/run_clang_format.py -e "*/third_party/*" -e "*/install/*" -e "*/toolchain/*" -ir --clang-format-executable=${LLVM_INSTALL_DIR}/bin/clang-format ./
 ```
 
-Note that third party applications should not be formatted. You can alternatively also run
+Note that third party applications should not be formatted. You can alternatively also run:
 ```
 make format
 ```

README.md

@@ -1,6 +1,12 @@
 # Deeploy
 
-Deeploy is a python tool to generate low-level optimized C Code for multi-cluster, heterogeneous SoCs. Its goal is to enable configurable deployment flows from a bottom-up compiler perspective, modelling target hardware in a fine-grained and modular manner.
+![CI](https://github.com/pulp-platform/Deeploy/actions/workflows/CI.yml/badge.svg?branch=devel)
+![Docker](https://github.com/pulp-platform/Deeploy/actions/workflows/BuildDocker.yml/badge.svg)
+[![GitHub last commit](https://img.shields.io/github/last-commit/pulp-platform/Deeploy)](#)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+![](https://img.shields.io/badge/Provided_by_PULP_Platform-24AF4B)
+
+Deeploy is an ONNX-to-C compiler that generates low-level optimized C Code for multi-cluster, heterogeneous SoCs. Its goal is to enable configurable deployment flows from a bottom-up compiler perspective, modeling target hardware in a fine-grained and modular manner.
 
 Deeploy is developed as part of the PULP project, a joint effort between ETH Zurich and the University of Bologna.
 
@@ -10,12 +16,69 @@ Unless specified otherwise in the respective file headers, all code checked into
 
 ## Getting started
 
-To install Deeploy, simply run
+Installing Deeploy is as simple as running:
 ```
 pip install -e .
 ```
-to download and install the Python dependencies. Run
+However, to run the code generated by Deeploy on a certain target, you need the toolchains and the simulators associated with this platform.
+
+We provide a Docker container where Deeploy works Out-of-the-Box (*i.e.* with all the dependencies pre-installed). To pull the docker image, run:
+```
+docker pull ghcr.io/pulp-platform/deeploy:main
+```
+Then you can start the container in interactive mode with:
+```
+docker run -it ghcr.io/pulp-platform/deeploy:main
+```
+From the container, clone Deeploy, its submodules, and install the package with:
+```
+git clone https://github.com/pulp-platform/Deeploy.git && cd Deeploy
+git submodule update --init --recursive
+pip install -e .
+```
+Congratulations, you installed Deeploy and its dependencies! Now, to test your installation let's run one simple test on each platform with the following commands:
+```
+cd DeeployTest && source /app/install/pulp-sdk/configs/siracusa.sh
+python testRunner_generic.py -t Tests/Adder
+python testRunner_cortexm.py -t Tests/Adder
+python testRunner_mempool.py -t Tests/Adder
+python testRunner_siracusa.py -t Tests/Adder --cores=8
+```
+
+You can find the ONNX file in `DeeployTest/Tests/Adder`, to visualize it, you can use [Netron](https://netron.app/). You can also find the generated code for the platform X in `TEST_X` in `DeeployTest` and you should notice that the generated code for the `Adder` test is very simple. However, this gets more complex when you add tiling. Let's generate the code for a single layer but using tiling this time:
+```
+python testRunner_tiled_siracusa.py -t Tests/testMatMul --cores=8 --l1=16000
+``` 
+Now you can open the generated code in `DeeployTest/TEST_SIRACUSA/Tests/testMatMul/Network.c` and see how we executed a tiled layer.
+
+## Supported Platforms
+
+- **Generic CPU:**
+- **CortexM Processors:**
+    - Simulators: [QEMU](https://www.qemu.org/)
+- **MemPool extended with ITA:**
+    - Hardware: [Mempool paper](https://arxiv.org/abs/2303.17742), [ITA paper](https://arxiv.org/abs/2307.03493)
+    - Simulators: [Banshee](https://github.com/pulp-platform/banshee)
+- **Siracusa:**
+    - Hardware: [Siracusa paper](https://arxiv.org/abs/2312.14750)
+    - Simulators: [GVSOC](https://github.com/gvsoc/gvsoc)
+
+## Documentation
+
+To build the documentation, simply run:
 ```
 make docs
 ```
-and open `docs/_build/html/index.html` for more extensive documentation & getting started guides.
+Then open `docs/_build/html/index.html` for more extensive documentation & getting-started guides.
+
+## Publications
+
+### ESWEEK 2024: Deeploy: Enabling Energy-Efficient Deployment of Small Language Models On Heterogeneous Microcontrollers
+```
+@article{scherer2024deeploy,
+  title={Deeploy: Enabling Energy-Efficient Deployment of Small Language Models On Heterogeneous Microcontrollers},
+  author={Scherer, Moritz and Macan, Luka and Jung, Victor and Wiese, Philip and Bompani, Luca and Burrello, Alessio and Conti, Francesco and Benini, Luca},
+  journal={arXiv preprint arXiv:2408.04413},
+  year={2024}
+}
+```