Merge branch 'main' into dual-ported-ram-fix

.github/workflows/main.yml

@@ -81,6 +81,7 @@ jobs:
           - { count: "32", width: "32", variant: "DEFAULT" }
           # - { count: "32", width: "32", variant: "1RW1R" } # Timeout
           - { count: "32", width: "32", variant: "2R1W" }
+          - { count: "128", width: "32", variant: "DEFAULT" }
           - { count: "256", width: "8", variant: "DEFAULT" }
           - { count: "256", width: "8", variant: "1RW1R" }
           - { count: "256", width: "16", variant: "DEFAULT" }
@@ -90,21 +91,36 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
+      - name: Setup Nix
+        uses: cachix/install-nix-action@v22
+        with:
+          nix_path: nixpkgs=channel:nixos-23.05
+      - name: Setup Cachix
+        uses: cachix/cachix-action@v12
+        with:
+          name: openlane
       - name: Run
         run: |
-          pip3 install --upgrade --no-cache-dir -r ./requirements.txt
-
           building_blocks=ram
           if [ "${{ matrix.variant }}" == "2R1W" ]; then
             building_blocks=rf
           fi
 
-          ./dffram.py\
-            -s ${{ matrix.count }}x${{ matrix.width }}\
-            -b sky130A:sky130_fd_sc_hd:$building_blocks\
-            -v ${{ matrix.variant }}
+          nix-shell --pure --run "\
+            ./dffram.py ${{ matrix.count }}x${{ matrix.width }}\
+            -p sky130A\
+            -s sky130_fd_sc_hd\
+            -v ${{ matrix.variant }}\
+            -b $building_blocks\
+          "
 
-          echo "PRODUCTS_PATH=$(cat ./products_path)" >> $GITHUB_ENV
+          echo "PRODUCTS_PATH=$(echo products/*)" >> $GITHUB_ENV
+      # - name: Upload Build Folder [TEMP]
+      #   uses: actions/upload-artifact@v3
+      #   if: always()
+      #   with:
+      #     name: BUILD_${{ matrix.count }}x${{ matrix.width }}_${{ matrix.variant }}
+      #     path: ./build
       - name: Upload Final Views
         uses: actions/upload-artifact@v3
         with:

.gitignore

@@ -29,4 +29,6 @@ support/
 *.cvcrc
 *.xz
 venv/
-products_path
+products_path
+/products_path
+/products

Makefile

@@ -1,24 +1,24 @@
 all: dist
 
 .PHONY: dist
-dist: venv/created
+dist: venv/manifest.txt
 	./venv/bin/python3 setup.py sdist bdist_wheel
 
 .PHONY: lint
-lint: venv/created
+lint: venv/manifest.txt
 	./venv/bin/black --check .
 	./venv/bin/flake8 .
 
-venv: venv/created
-venv/created: ./requirements_dev.txt ./requirements.txt
+venv: venv/manifest.txt
+venv/manifest.txt: ./requirements_dev.txt
 	rm -rf venv
 	python3 -m venv ./venv
-	./venv/bin/python3 -m pip install --upgrade pip
-	./venv/bin/python3 -m pip install --upgrade wheel
-	./venv/bin/python3 -m pip install --upgrade\
-		-r ./requirements_dev.txt\
-		-r ./requirements.txt
-	touch venv/created
+	PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade pip
+	PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade wheel
+	PYTHONPATH= ./venv/bin/python3 -m pip install --upgrade\
+		-r ./requirements_dev.txt
+	PYTHONPATH= ./venv/bin/python3 -m pip freeze > $@
+	touch venv/manifest.txt
 
 .PHONY: veryclean
 veryclean: clean

Readme.md

@@ -11,77 +11,105 @@
 
 Standard Cell Library based Memory Compiler using DFF/Latch cells.
 
-# ✨ Quick Usage
-You can try the [Google Colaboratory](https://colab.research.google.com/github/Cloud-V/DFFRAM/blob/main/dffram.ipynb), but also...
+# ✨ Installation & Usage
 
-[Get **Docker**](https://docs.docker.com/get-docker/), set it up nicely, then, in your terminal:
+See [this document](./docs/Usage.md).
 
-```sh
-pip3 install --user --no-cache-dir --upgrade ./requirements.txt
-./dffram.py -s 32x32
-```
+You can try the
+[Google Colaboratory](https://colab.research.google.com/github/Cloud-V/DFFRAM/blob/main/dffram.ipynb),
+but it is a bit out-of-date at this point.
 
-If all goes well, you've placed your first register file!
+## Platform Support Status
+
+| Configured Platform | Working | Silicon-proven\* |
+| - | - | - |
+| `sky130A` | Yes | Yes |
+| `sky130B` | Yes | No |
+| `gf180mcuD` | No\* (Hold violations in the Netlist) | No |
+
+> \* Silicon proven does not imply that you should use it without whole-system,
+> timing-annotated simulation to make sure that it works for your circuit.
+>
+> There may be design-specific complications that may render DFFRAM (and indeed
+> the entire chip) unusable. Proceed with caution.
 
 # Overview
-The objective of this project is to develop a DFF/Latch-based RAM, Register File and Cache custom compilation flow that utilizes standard cell libraries following a standard ASIC (Application Specific Integrated Circuit) implementation approach. Different views (HDL netlist, HDL functional models, LEF, GDS, Timing, …) are all generated for a given size configuration.
 
-The layout targets highly compact designs (85%+) as the cells are placed on the floor plan using a custom placer. Moreover, the custom placer ensures that the routing will be relatively simple. Currently, the compiler uses OpenROAD routers to route the macros with great success. 
+The objective of this project is to develop a DFF/Latch-based RAM, Register File
+and Cache custom compilation flow that utilizes standard cell libraries
+following a standard ASIC (Application Specific Integrated Circuit)
+implementation approach. Different views (HDL netlist, HDL functional models,
+LEF, GDS, Timing, …) are all generated for a given size configuration.
+
+The layout targets highly compact designs (85%+) as the cells are placed on the
+floor plan using a custom placer. Moreover, the custom placer ensures that the
+routing will be relatively simple. Currently, the compiler uses OpenROAD routers
+to route the macros with great success.
 
-The Compiler relies on basic building blocks to construct the layout of different RAM/RF/Cache configurations. Check [the compiler documentation](./docs/) for more info. The following shows how a 32x32 memory (DFF based) is constructed.
+The Compiler relies on basic building blocks to construct the layout of
+different RAM/RF/Cache configurations. Check
+[the compiler documentation](./docs/) for more info. The following shows how a
+32x32 memory (DFF based) is constructed.
 
 ![](./docs/img/ram_ex.png)
 
-The generated layouts by the DFFRAM compilers for RAM32 as well as its building blocks are as follows:
-- First, a byte, which is just 8 bits placed together...
-![GDS layout of a byte](./docs/img/1x8.png)
+The generated layouts by the DFFRAM compilers for RAM32 as well as its building
+blocks are as follows:
 
-- Put four of those side by side, and you get a 32-bit word...
-![GDS layout of a word](./docs/img/1x32.png)
+* First, a byte, which is just 8 bits placed together...
+  ![GDS layout of a byte](./docs/img/1x8.png)
 
-- Stack eight of those for an 8 word bank of RAM...
-![GDS layout of 8 words stacked vertically](./docs/img/8x32.png)
+* Put four of those side by side, and you get a 32-bit word...
+  ![GDS layout of a word](./docs/img/1x32.png)
 
-- And stack 4 of these 8 words for a kilobit of RAM!
-![GDS layout of 4x8 words stacked vertically](./docs/img/32x32.png)
+* Stack eight of those for an 8 word bank of RAM...
+  ![GDS layout of 8 words stacked vertically](./docs/img/8x32.png)
 
-- We can keep going, but these images aren't getting any smaller. As a bonus though, here is 64 kilobits:
-![8kbytes](./docs/img/8kb_layout.png)
+* And stack 4 of these 8 words for a kilobit of RAM!
+  ![GDS layout of 4x8 words stacked vertically](./docs/img/32x32.png)
 
-> That stuff you see on the right of each image? It's clock gates, decoders and the like. Don't worry about it.
+* We can keep going, but these images aren't getting any smaller. As a bonus
+  though, here is 64 kilobits: ![8kbytes](./docs/img/8kb_layout.png)
 
+> That stuff you see on the right of each image? It's clock gates, decoders and
+> the like. Don't worry about it.
 
 Currently, the can compiler generate the layout of the following configurations:
 
 > 1RW1R variants are temporarily disabled due to a bug.
 
-- RAM
-  - 32 words with byte write enable (1RW and 1RW1R).
-  - 128 words with byte write enable (1RW and 1RW1R).
-  - 256 words with byte write enable (1RW and 1RW1R).
-  - 512 words with byte write enable (1RW and 1RW1R).
-  - 1024 words with byte write enable (1RW and 1RW1R).
-  - 2048 words with byte write enable (1RW and 1RW1R).
-- Register File
-  - 32 x 32-bit words (2R1W)
-
-The [`OpenLane/`](./OpenLane) folder will contain good known OpenLane configurations to build DFFRAM different macros. 
-
+* RAM
+  * 32 words with byte write enable (1RW and 1RW1R).
+  * 128 words with byte write enable (1RW and 1RW1R).
+  * 256 words with byte write enable (1RW and 1RW1R).
+  * 512 words with byte write enable (1RW and 1RW1R).
+  * 1024 words with byte write enable (1RW and 1RW1R).
+  * 2048 words with byte write enable (1RW and 1RW1R).
+* Register File
+  * 32 x 32-bit words (2R1W)
+
+The [`OpenLane/`](./OpenLane) folder will contain good known OpenLane
+configurations to build DFFRAM different macros.
+
 ## File Structure
+
 * `.github` contains files for GitHub actions.
 * `docs/` contains documentation (😮)
-* `rtl/` contains RTL RAM file generators for benchmarking and comparison purposes.
+* `rtl/` contains RTL RAM file generators for benchmarking and comparison
+  purposes.
 * `platforms/` contains PDK-specific files:
   * `<pdk-name>/`
     * `<scl-name>/`
-      * `_building_blocks/` contains a hierarchy of building blocks supported by the compiler.
+      * `_building_blocks/` contains a hierarchy of building blocks supported by
+        the compiler.
 * `placeram/` is the custom placer Python module.
 * `scripts/` has assisting scripts used by the flow.
 * `dffram.py` is the compilation flow going from building blocks to LVS.
 
 # Comparisons
-The following table compares the areas and bit densities of RAM macros generated using different means.
 
+The following table compares the areas and bit densities of RAM macros generated
+using different means.
 
 <table>
   <tr>
@@ -124,8 +152,8 @@ The following table compares the areas and bit densities of RAM macros generated
     <td> 1,584.24 x 788.8 </td> <td> 26,196 </td>
     <td> 1940.45 x 1951.17 </td> <td> 8,654 </td>
     <td> 2,074 x 2,085 </td> <td> 7,578 </td>
-    
-  </tr>
+
+</tr>
   <tr>
     <td> 8 kbytes </td>
     <td> N/A </td> <td> N/A </td>
@@ -135,24 +163,27 @@ The following table compares the areas and bit densities of RAM macros generated
   </tr>
 </table>
 
-
-
-<sup>1</sup> All support 32-bit word reads and 1, 2, and 4 bytes writes.  
-<sup>2</sup> Values are based on the original layout produced by the compiler. OpenRAM macros are typically wrapped to be useful w/ automated PnR ASIC flows.
+<sup>1</sup> All support 32-bit word reads and 1, 2, and 4 bytes
+writes.\
+<sup>2</sup> Values are based on the original layout produced by the
+compiler. OpenRAM macros are typically wrapped to be useful w/ automated PnR
+ASIC flows.
 
 # ⚖️ Copyright and Licensing
+
 <a id="copyright-and-licensing"></a>
-Copyright ©2020-2022 The American University in Cairo
 
-Licensed under the Apache License, Version 2.0 (the "Open Source License");
-you may not use this file except in compliance with the Open Source License.
-You may obtain a copy of the Open Source License at the root of this repository
-(see the file 'License') or at
+Copyright ©2020-2023 The American University in Cairo
+
+Licensed under the Apache License, Version 2.0 (the "Open Source License"); you
+may not use this file except in compliance with the Open Source License. You may
+obtain a copy of the Open Source License at the root of this repository (see the
+file 'License') or at
 
 > http://www.apache.org/licenses/LICENSE-2.0
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the Open Source License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the Open Source License for the specific language governing permissions and
-limitations under the Open Source License.
+Unless required by applicable law or agreed to in writing, software distributed
+under the Open Source License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Open
+Source License for the specific language governing permissions and limitations
+under the Open Source License.

dffram.ipynb

@@ -6,13 +6,15 @@
     "id": "eukW5KG9kq7A"
    },
    "source": [
-    "#  DFFRAM Compiler\n",
+    "# DFFRAM Compiler\n",
     "\n",
+    "Standard Cell Library based Memory Compiler using DFF/Latch cells.\n",
     "\n",
-    " Standard Cell Library based Memory Compiler using DFF/Latch cells.\n",
     "\n",
+    "## Warning!\n",
     "\n",
-    "\n"
+    "This notebook should still work, but is out of date and does not reflect the\n",
+    "latest DFFRAM release. Use at your own risk!"
    ]
   },
   {
@@ -325,7 +327,7 @@
    "provenance": []
   },
   "kernelspec": {
-   "display_name": "Python 3.10.9 64-bit",
+   "display_name": "Python 3.10.9 ('venv': venv)",
    "language": "python",
    "name": "python3"
   },
@@ -343,7 +345,7 @@
   },
   "vscode": {
    "interpreter": {
-    "hash": "3fe098a60de41da4d418149dd85333239847aa92272c8f79d3c6f03653219927"
+    "hash": "192516fa94e535c4f5cf27eeef389e5df5ced4f52a77092f31776bfbcc9cff03"
    }
   }
  },