diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 0000000..9dbf7b9 --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,27 @@ +ARG VARIANT=ubuntu-22.04 +FROM mcr.microsoft.com/vscode/devcontainers/base:${VARIANT} + +ENV DEBIAN_FRONTEND=noninteractive +ENV PDK_ROOT=/home/vscode/ttsetup/pdk +ENV PDK=sky130A + +RUN apt update +RUN apt install -y iverilog gtkwave python3 python3-pip python3-venv python3-tk python-is-python3 libcairo2 verilator libpng-dev libqhull-dev + +# Clone tt-support-tools +RUN mkdir -p /ttsetup +RUN git clone -b tt10 https://github.com/TinyTapeout/tt-support-tools /ttsetup/tt-support-tools + +COPY test/requirements.txt /ttsetup/test_requirements.txt +COPY .devcontainer/copy_tt_support_tools.sh /ttsetup + +RUN pip3 install -r /ttsetup/test_requirements.txt -r /ttsetup/tt-support-tools/requirements.txt + +# Install verible (for formatting) +RUN umask 022 && \ + curl -L https://github.com/chipsalliance/verible/releases/download/v0.0-3795-gf4d72375/verible-v0.0-3795-gf4d72375-linux-static-x86_64.tar.gz | \ + tar zxf - -C /usr/local --strip-components=1 && \ + chmod 755 /usr/local/bin + +# Install openlane +RUN pip3 install openlane==2.1.5 diff --git a/.devcontainer/copy_tt_support_tools.sh b/.devcontainer/copy_tt_support_tools.sh new file mode 100755 index 0000000..7064826 --- /dev/null +++ b/.devcontainer/copy_tt_support_tools.sh @@ -0,0 +1,6 @@ +#! /bin/sh + +if [ ! -L tt ]; then + cp -R /ttsetup/tt-support-tools tt + cd tt && git pull && cd .. +fi diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..74128fb --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,29 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at: +// https://github.com/microsoft/vscode-dev-containers/tree/v0.183.0/containers/ubuntu +{ + "name": "Tiny Tapeout Dev Container", + "build": { + "dockerfile": "Dockerfile", + "context": ".." + }, + "runArgs": [ + "--memory=10GB" + ], + "customizations": { + "vscode": { + "settings": { + "terminal.integrated.defaultProfile.linux": "bash" + }, + "extensions": ["mshr-h.veriloghdl", "surfer-project.surfer"] + } + }, + "features": { + "ghcr.io/devcontainers/features/docker-in-docker:2": { + "moby": true, + "azureDnsAutoDetection": true, + "version": "latest", + "dockerDashComposeVersion": "none" + } + }, + "postStartCommand": "/ttsetup/copy_tt_support_tools.sh" +} diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..f93f144 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,17 @@ +name: docs + +on: + push: + workflow_dispatch: + +jobs: + docs: + runs-on: ubuntu-24.04 + steps: + - name: Checkout repo + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Build docs + uses: TinyTapeout/tt-gds-action/docs@tt10 diff --git a/.github/workflows/fpga.yaml b/.github/workflows/fpga.yaml new file mode 100644 index 0000000..a9faaa4 --- /dev/null +++ b/.github/workflows/fpga.yaml @@ -0,0 +1,19 @@ +name: fpga + +on: + push: + # Comment out (or remove) the following line to run the FPGA workflow on every push: + branches: none + workflow_dispatch: + +jobs: + fpga: + runs-on: ubuntu-24.04 + steps: + - name: checkout repo + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: FPGA bitstream for TT ASIC Sim (ICE40UP5K) + uses: TinyTapeout/tt-gds-action/fpga/ice40up5k@tt10 diff --git a/.github/workflows/gds.yaml b/.github/workflows/gds.yaml new file mode 100644 index 0000000..9b4c480 --- /dev/null +++ b/.github/workflows/gds.yaml @@ -0,0 +1,47 @@ +name: gds + +on: + push: + workflow_dispatch: + +jobs: + gds: + runs-on: ubuntu-24.04 + steps: + - name: checkout repo + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Build GDS + uses: TinyTapeout/tt-gds-action@tt10 + with: + flow: openlane2 + + precheck: + needs: gds + runs-on: ubuntu-24.04 + steps: + - name: Run Tiny Tapeout Precheck + uses: TinyTapeout/tt-gds-action/precheck@tt10 + + gl_test: + needs: gds + runs-on: ubuntu-24.04 + steps: + - name: checkout repo + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: GL test + uses: TinyTapeout/tt-gds-action/gl_test@tt10 + + viewer: + needs: gds + runs-on: ubuntu-24.04 + permissions: + pages: write # to deploy to Pages + id-token: write # to verify the deployment originates from an appropriate source + steps: + - uses: TinyTapeout/tt-gds-action/viewer@tt10 diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml new file mode 100644 index 0000000..cb31af4 --- /dev/null +++ b/.github/workflows/test.yaml @@ -0,0 +1,47 @@ +name: test +on: [push, workflow_dispatch] +jobs: + test: + runs-on: ubuntu-24.04 + steps: + - name: Checkout repo + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Install iverilog + shell: bash + run: sudo apt-get update && sudo apt-get install -y iverilog + + # Set Python up and install cocotb + - name: Setup python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install Python packages + shell: bash + run: pip install -r test/requirements.txt + + - name: Run tests + run: | + cd test + make clean + make + # make will return success even if the test fails, so check for failure in the results.xml + ! grep failure results.xml + + - name: Test Summary + uses: test-summary/action@v2.3 + with: + paths: "test/results.xml" + if: always() + + - name: upload vcd + if: success() || failure() + uses: actions/upload-artifact@v4 + with: + name: test-vcd + path: | + test/tb.vcd + test/results.xml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8746fa0 --- /dev/null +++ b/.gitignore @@ -0,0 +1,11 @@ +.DS_Store +.idea +*.vcd +runs +tt_submission +src/user_config.json +src/config_merged.json +test/sim_build +test/__pycache__/ +test/results.xml +test/gate_level_netlist.v diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..12c4625 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,6 @@ +{ + "recommendations": [ + "mshr-h.veriloghdl", + "surfer-project.surfer" + ] +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..c8d6ad4 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,4 @@ +{ + "verilog.linting.linter": "verilator", + "verilog.formatting.verilogHDL.formatter": "verible-verilog-format" +} diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..261eeb9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md new file mode 100644 index 0000000..68ba6ed --- /dev/null +++ b/README.md @@ -0,0 +1,41 @@ +![](../../workflows/gds/badge.svg) ![](../../workflows/docs/badge.svg) ![](../../workflows/test/badge.svg) ![](../../workflows/fpga/badge.svg) + +# Tiny Tapeout Verilog Project Template + +- [Read the documentation for project](docs/info.md) + +## What is Tiny Tapeout? + +Tiny Tapeout is an educational project that aims to make it easier and cheaper than ever to get your digital and analog designs manufactured on a real chip. + +To learn more and get started, visit https://tinytapeout.com. + +## Set up your Verilog project + +1. Add your Verilog files to the `src` folder. +2. Edit the [info.yaml](info.yaml) and update information about your project, paying special attention to the `source_files` and `top_module` properties. If you are upgrading an existing Tiny Tapeout project, check out our [online info.yaml migration tool](https://tinytapeout.github.io/tt-yaml-upgrade-tool/). +3. Edit [docs/info.md](docs/info.md) and add a description of your project. +4. Adapt the testbench to your design. See [test/README.md](test/README.md) for more information. + +The GitHub action will automatically build the ASIC files using [OpenLane](https://www.zerotoasiccourse.com/terminology/openlane/). + +## Enable GitHub actions to build the results page + +- [Enabling GitHub Pages](https://tinytapeout.com/faq/#my-github-action-is-failing-on-the-pages-part) + +## Resources + +- [FAQ](https://tinytapeout.com/faq/) +- [Digital design lessons](https://tinytapeout.com/digital_design/) +- [Learn how semiconductors work](https://tinytapeout.com/siliwiz/) +- [Join the community](https://tinytapeout.com/discord) +- [Build your design locally](https://www.tinytapeout.com/guides/local-hardening/) + +## What next? + +- [Submit your design to the next shuttle](https://app.tinytapeout.com/). +- Edit [this README](README.md) and explain your design, how it works, and how to test it. +- Share your project on your social network of choice: + - LinkedIn [#tinytapeout](https://www.linkedin.com/search/results/content/?keywords=%23tinytapeout) [@TinyTapeout](https://www.linkedin.com/company/100708654/) + - Mastodon [#tinytapeout](https://chaos.social/tags/tinytapeout) [@matthewvenn](https://chaos.social/@matthewvenn) + - X (formerly Twitter) [#tinytapeout](https://twitter.com/hashtag/tinytapeout) [@tinytapeout](https://twitter.com/tinytapeout) diff --git a/docs/info.md b/docs/info.md new file mode 100644 index 0000000..ce1f04c --- /dev/null +++ b/docs/info.md @@ -0,0 +1,20 @@ + + +## How it works + +Explain how your project works + +## How to test + +Explain how to use your project + +## External hardware + +List external hardware used in your project (e.g. PMOD, LED display, etc), if any diff --git a/info.yaml b/info.yaml new file mode 100644 index 0000000..50bb751 --- /dev/null +++ b/info.yaml @@ -0,0 +1,55 @@ +# Tiny Tapeout project information +project: + title: "" # Project title + author: "" # Your name + discord: "" # Your discord username, for communication and automatically assigning you a Tapeout role (optional) + description: "" # One line description of what your project does + language: "Verilog" # other examples include SystemVerilog, Amaranth, VHDL, etc + clock_hz: 0 # Clock frequency in Hz (or 0 if not applicable) + + # How many tiles your design occupies? A single tile is about 167x108 uM. + tiles: "1x1" # Valid values: 1x1, 1x2, 2x2, 3x2, 4x2, 6x2 or 8x2 + + # Your top module name must start with "tt_um_". Make it unique by including your github username: + top_module: "tt_um_example" + + # List your project's source files here. + # Source files must be in ./src and you must list each source file separately, one per line. + # Don't forget to also update `PROJECT_SOURCES` in test/Makefile. + source_files: + - "project.v" + +# The pinout of your project. Leave unused pins blank. DO NOT delete or add any pins. +pinout: + # Inputs + ui[0]: "" + ui[1]: "" + ui[2]: "" + ui[3]: "" + ui[4]: "" + ui[5]: "" + ui[6]: "" + ui[7]: "" + + # Outputs + uo[0]: "" + uo[1]: "" + uo[2]: "" + uo[3]: "" + uo[4]: "" + uo[5]: "" + uo[6]: "" + uo[7]: "" + + # Bidirectional pins + uio[0]: "" + uio[1]: "" + uio[2]: "" + uio[3]: "" + uio[4]: "" + uio[5]: "" + uio[6]: "" + uio[7]: "" + +# Do not change! +yaml_version: 6 diff --git a/src/config.json b/src/config.json new file mode 100644 index 0000000..b9701da --- /dev/null +++ b/src/config.json @@ -0,0 +1,75 @@ +{ + "//": "DO NOT EDIT THIS FILE before reading the comments below:", + + "//": "This is the default configuration for Tiny Tapeout projects. It should fit most designs.", + "//": "If you change it, please make sure you understand what you are doing. We are not responsible", + "//": "if your project fails because of a bad configuration.", + + "//": "!!! DO NOT EDIT THIS FILE unless you know what you are doing !!!", + + "//": "If you get stuck with this config, please open an issue or get in touch via the discord.", + + "//": "Here are some of the variables you may want to change:", + + "//": "PL_TARGET_DENSITY_PCT - You can increase this if Global Placement fails with error GPL-0302.", + "//": "Users have reported that values up to 80 worked well for them.", + "PL_TARGET_DENSITY_PCT": 60, + + "//": "CLOCK_PERIOD - Increase this in case you are getting setup time violations.", + "//": "The value is in nanoseconds, so 20ns == 50MHz.", + "CLOCK_PERIOD": 20, + + "//": "Hold slack margin - Increase them in case you are getting hold violations.", + "PL_RESIZER_HOLD_SLACK_MARGIN": 0.1, + "GRT_RESIZER_HOLD_SLACK_MARGIN": 0.05, + + "//": "RUN_LINTER, LINTER_INCLUDE_PDK_MODELS - Disabling the linter is not recommended!", + "RUN_LINTER": 1, + "LINTER_INCLUDE_PDK_MODELS": 1, + + "//": "If you need a custom clock configuration, read the following documentation first:", + "//": "https://tinytapeout.com/faq/#how-can-i-map-an-additional-external-clock-to-one-of-the-gpios", + "CLOCK_PORT": "clk", + + "//": "Configuration docs: https://openlane.readthedocs.io/en/latest/reference/configuration.html", + + "//": "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!", + "//": "!!! DO NOT CHANGE ANYTHING BELOW THIS POINT !!!", + "//": "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!", + + "//": "Save some time", + "RUN_KLAYOUT_XOR": 0, + "RUN_KLAYOUT_DRC": 0, + + "//": "Don't put clock buffers on the outputs", + "DESIGN_REPAIR_BUFFER_OUTPUT_PORTS": 0, + + "//": "Reduce wasted space", + "TOP_MARGIN_MULT": 1, + "BOTTOM_MARGIN_MULT": 1, + "LEFT_MARGIN_MULT": 6, + "RIGHT_MARGIN_MULT": 6, + + "//": "Absolute die size", + "FP_SIZING": "absolute", + + "GRT_ALLOW_CONGESTION": 1, + + "FP_IO_HLENGTH": 2, + "FP_IO_VLENGTH": 2, + + "FP_PDN_VPITCH": 38.87, + + "//": "Clock", + "RUN_CTS": 1, + + "//": "Don't use power rings or met5 layer", + "FP_PDN_MULTILAYER": 0, + "RT_MAX_LAYER": "met4", + + "//": "MAGIC_DEF_LABELS may cause issues with LVS", + "MAGIC_DEF_LABELS": 0, + + "//": "Only export pin area in LEF (without any connected nets)", + "MAGIC_WRITE_LEF_PINONLY": 1 +} diff --git a/src/project.v b/src/project.v new file mode 100644 index 0000000..cd6f740 --- /dev/null +++ b/src/project.v @@ -0,0 +1,27 @@ +/* + * Copyright (c) 2024 Your Name + * SPDX-License-Identifier: Apache-2.0 + */ + +`default_nettype none + +module tt_um_example ( + input wire [7:0] ui_in, // Dedicated inputs + output wire [7:0] uo_out, // Dedicated outputs + input wire [7:0] uio_in, // IOs: Input path + output wire [7:0] uio_out, // IOs: Output path + output wire [7:0] uio_oe, // IOs: Enable path (active high: 0=input, 1=output) + input wire ena, // always 1 when the design is powered, so you can ignore it + input wire clk, // clock + input wire rst_n // reset_n - low to reset +); + + // All output pins must be assigned. If not used, assign to 0. + assign uo_out = ui_in + uio_in; // Example: ou_out is the sum of ui_in and uio_in + assign uio_out = 0; + assign uio_oe = 0; + + // List all unused inputs to prevent warnings + wire _unused = &{ena, clk, rst_n, 1'b0}; + +endmodule diff --git a/test/Makefile b/test/Makefile new file mode 100644 index 0000000..6fdbe36 --- /dev/null +++ b/test/Makefile @@ -0,0 +1,42 @@ +# Makefile +# See https://docs.cocotb.org/en/stable/quickstart.html for more info + +# defaults +SIM ?= icarus +TOPLEVEL_LANG ?= verilog +SRC_DIR = $(PWD)/../src +PROJECT_SOURCES = project.v + +ifneq ($(GATES),yes) + +# RTL simulation: +SIM_BUILD = sim_build/rtl +VERILOG_SOURCES += $(addprefix $(SRC_DIR)/,$(PROJECT_SOURCES)) +COMPILE_ARGS += -I$(SRC_DIR) + +else + +# Gate level simulation: +SIM_BUILD = sim_build/gl +COMPILE_ARGS += -DGL_TEST +COMPILE_ARGS += -DFUNCTIONAL +COMPILE_ARGS += -DUSE_POWER_PINS +COMPILE_ARGS += -DSIM +COMPILE_ARGS += -DUNIT_DELAY=\#1 +VERILOG_SOURCES += $(PDK_ROOT)/sky130A/libs.ref/sky130_fd_sc_hd/verilog/primitives.v +VERILOG_SOURCES += $(PDK_ROOT)/sky130A/libs.ref/sky130_fd_sc_hd/verilog/sky130_fd_sc_hd.v + +# this gets copied in by the GDS action workflow +VERILOG_SOURCES += $(PWD)/gate_level_netlist.v + +endif + +# Include the testbench sources: +VERILOG_SOURCES += $(PWD)/tb.v +TOPLEVEL = tb + +# MODULE is the basename of the Python test file +MODULE = test + +# include cocotb's make rules to take care of the simulator setup +include $(shell cocotb-config --makefiles)/Makefile.sim diff --git a/test/README.md b/test/README.md new file mode 100644 index 0000000..78913e2 --- /dev/null +++ b/test/README.md @@ -0,0 +1,37 @@ +# Sample testbench for a Tiny Tapeout project + +This is a sample testbench for a Tiny Tapeout project. It uses [cocotb](https://docs.cocotb.org/en/stable/) to drive the DUT and check the outputs. +See below to get started or for more information, check the [website](https://tinytapeout.com/hdl/testing/). + +## Setting up + +1. Edit [Makefile](Makefile) and modify `PROJECT_SOURCES` to point to your Verilog files. +2. Edit [tb.v](tb.v) and replace `tt_um_example` with your module name. + +## How to run + +To run the RTL simulation: + +```sh +make -B +``` + +To run gatelevel simulation, first harden your project and copy `../runs/wokwi/results/final/verilog/gl/{your_module_name}.v` to `gate_level_netlist.v`. + +Then run: + +```sh +make -B GATES=yes +``` + +## How to view the VCD file + +Using GTKWave +```sh +gtkwave tb.vcd tb.gtkw +``` + +Using Surfer +```sh +surfer tb.vcd +``` diff --git a/test/requirements.txt b/test/requirements.txt new file mode 100644 index 0000000..e013f54 --- /dev/null +++ b/test/requirements.txt @@ -0,0 +1,2 @@ +pytest==8.2.2 +cocotb==1.9.1 diff --git a/test/tb.gtkw b/test/tb.gtkw new file mode 100644 index 0000000..c92ca3c --- /dev/null +++ b/test/tb.gtkw @@ -0,0 +1,39 @@ +[*] +[*] GTKWave Analyzer v3.4.0 (w)1999-2022 BSI +[*] Mon Nov 20 16:00:28 2023 +[*] +[dumpfile] "/home/uri/p/tt-new-template-proto/test/tb.vcd" +[dumpfile_mtime] "Mon Nov 20 15:58:34 2023" +[dumpfile_size] 1110 +[savefile] "/home/uri/p/tt-new-template-proto/test/tb.gtkw" +[timestart] 0 +[size] 1376 600 +[pos] -1 -1 +*-24.534533 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 +[treeopen] tb. +[sst_width] 297 +[signals_width] 230 +[sst_expanded] 1 +[sst_vpaned_height] 158 +@28 +tb.user_project.ena +@29 +tb.user_project.clk +@28 +tb.user_project.rst_n +@200 +-Inputs +@22 +tb.user_project.ui_in[7:0] +@200 +-Bidirectional Pins +@22 +tb.user_project.uio_in[7:0] +tb.user_project.uio_oe[7:0] +tb.user_project.uio_out[7:0] +@200 +-Output Pins +@22 +tb.user_project.uo_out[7:0] +[pattern_trace] 1 +[pattern_trace] 0 diff --git a/test/tb.v b/test/tb.v new file mode 100644 index 0000000..aebf272 --- /dev/null +++ b/test/tb.v @@ -0,0 +1,49 @@ +`default_nettype none +`timescale 1ns / 1ps + +/* This testbench just instantiates the module and makes some convenient wires + that can be driven / tested by the cocotb test.py. +*/ +module tb (); + + // Dump the signals to a VCD file. You can view it with gtkwave or surfer. + initial begin + $dumpfile("tb.vcd"); + $dumpvars(0, tb); + #1; + end + + // Wire up the inputs and outputs: + reg clk; + reg rst_n; + reg ena; + reg [7:0] ui_in; + reg [7:0] uio_in; + wire [7:0] uo_out; + wire [7:0] uio_out; + wire [7:0] uio_oe; +`ifdef GL_TEST + wire VPWR = 1'b1; + wire VGND = 1'b0; +`endif + + // Replace tt_um_example with your module name: + tt_um_example user_project ( + + // Include power ports for the Gate Level test: +`ifdef GL_TEST + .VPWR(VPWR), + .VGND(VGND), +`endif + + .ui_in (ui_in), // Dedicated inputs + .uo_out (uo_out), // Dedicated outputs + .uio_in (uio_in), // IOs: Input path + .uio_out(uio_out), // IOs: Output path + .uio_oe (uio_oe), // IOs: Enable path (active high: 0=input, 1=output) + .ena (ena), // enable - goes high when design is selected + .clk (clk), // clock + .rst_n (rst_n) // not reset + ); + +endmodule diff --git a/test/test.py b/test/test.py new file mode 100644 index 0000000..fa7f92c --- /dev/null +++ b/test/test.py @@ -0,0 +1,40 @@ +# SPDX-FileCopyrightText: © 2024 Tiny Tapeout +# SPDX-License-Identifier: Apache-2.0 + +import cocotb +from cocotb.clock import Clock +from cocotb.triggers import ClockCycles + + +@cocotb.test() +async def test_project(dut): + dut._log.info("Start") + + # Set the clock period to 10 us (100 KHz) + clock = Clock(dut.clk, 10, units="us") + cocotb.start_soon(clock.start()) + + # Reset + dut._log.info("Reset") + dut.ena.value = 1 + dut.ui_in.value = 0 + dut.uio_in.value = 0 + dut.rst_n.value = 0 + await ClockCycles(dut.clk, 10) + dut.rst_n.value = 1 + + dut._log.info("Test project behavior") + + # Set the input values you want to test + dut.ui_in.value = 20 + dut.uio_in.value = 30 + + # Wait for one clock cycle to see the output values + await ClockCycles(dut.clk, 1) + + # The following assersion is just an example of how to check the output values. + # Change it to match the actual expected output of your module: + assert dut.uo_out.value == 50 + + # Keep testing the module by changing the input values, waiting for + # one or more clock cycles, and asserting the expected output values.