FABulous-FPGA 2.0.0b1__tar.gz

fabulous_fpga-2.0.0b1/.gitattributes

@@ -0,0 +1,2 @@
+# Set the default behavior, in case people don't have core.autocrlf set.
+* text=auto

fabulous_fpga-2.0.0b1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Execute command '....'
+3. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Example**
+Provide a minimal reproducible example.
+You may also provide your FABulous project.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Your Setup (please complete the following information):**
+ - OS: [e.g. Debian Linux]
+ - OS / kernel version: [e.g. 6.12.4-arch1-1]
+ - Python version: [e.g. 3.12.07]
+ - Yosys version: [e.g. 0.43]
+ - FABulous version / git commit id / git branch
+
+**Additional context**
+Add any other context about the problem here.

fabulous_fpga-2.0.0b1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,21 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+If you have questions about the usage of FABulous, please check the [FABulous discussions page](https://github.com/FPGA-Research/FABulous/discussions) .
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

fabulous_fpga-2.0.0b1/.github/actions/prepare_FABulous_container/action.yaml

@@ -0,0 +1,117 @@
+name: Prepare FABulous workflow
+description: Composite action to prepare a container with everything needed to run FABulous
+
+inputs:
+  python_version:
+    description: "Python version to use"
+    required: false
+    default: "3.12"
+  oss-cad-suite-nightly:
+    description: "Set true to use nightly version of oss-cad-suite."
+    required: false
+    default: "false"
+  additional_system_packages:
+    description: "Additional ubuntu packages to install"
+    required: false
+    default: ""
+  additional_python_packages:
+    description: "Additional python packages to install"
+    required: false
+    default: ""
+  install_ghdl_mcode:
+    description: "If false, ghdl mcode won't be installed and the oss-cad-suite llvm version is used"
+    required: false
+    default: "true"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python_version }}
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        version: "latest"
+        enable-cache: true
+    - name: Get OSS CAD Suite version
+      id: oss-cad-version
+      shell: bash
+      run: |
+        # Get the latest release info from YosysHQ/oss-cad-suite-build
+        # Use authenticated API call to avoid rate limits
+
+        if ${{ inputs.oss-cad-suite-nightly }}; then
+          echo "Get latest oss-cad-suite nightly version"
+          if [ -n "${{ github.token }}"]; then
+            VERSION=$(curl -s -H "Authorization: Bearer ${{ github.token }}" \
+              "https://api.github.com/repos/YosysHQ/oss-cad-suite-build/releases/latest" | \
+              jq -r '.tag_name // "unknown"')
+          else
+            VERSION=$(curl -s "https://api.github.com/repos/YosysHQ/oss-cad-suite-build/releases/latest" | \
+              jq -r '.tag_name // "unknown"')
+          fi
+
+          # Fallback to a fixed version if API call fails
+          if [ "$VERSION" = "unknown" ] || [ "$VERSION" = "null" ] || [ -z "$VERSION" ]; then
+            echo "Warning: Failed to get OSS CAD Suite version from API, using fallback"
+            VERSION="2025-07-01"  # Use a recent stable version as fallback
+          fi
+
+        else
+          echo "Get latest known working OSS CAD Suite version."
+          VERSION="2025-07-01"  # Use a recent stable version as fallback
+        fi
+
+        echo "Using OSS CAD Suite version: $VERSION"
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+    - name: Cache OSS CAD Suite
+      id: cache-oss-cad
+      uses: actions/cache@v4
+      with:
+        path: |
+          ${{ runner.temp }}/oss-cad-suite
+        key: oss-cad-suite-${{ runner.os }}-${{ steps.oss-cad-version.outputs.version }}
+        restore-keys: |
+          oss-cad-suite-${{ runner.os }}-${{ steps.oss-cad-version.outputs.version }}
+    - name: set up OSS CAD path
+      if: ${{ steps.cache-oss-cad.outputs.cache-hit == 'true' }}
+      shell: bash
+      run: |
+        echo "${{ runner.temp }}/oss-cad-suite/bin:$PATH" >> "$GITHUB_PATH"
+    - name: Set up OSS CAD suite
+      if: ${{ steps.cache-oss-cad.outputs.cache-hit != 'true' }}
+      uses: YosysHQ/setup-oss-cad-suite@v3
+      with:
+        github-token: ${{ github.token }}
+        version: ${{ steps.oss-cad-version.outputs.version }}
+    - name: Install GHDL mcode nightly
+      # GHDL mcode is required to test our fabric.
+      # The oss-cad-suite action installs GHDL, but with the LLVM backend, which is much slower for our simulation
+      uses: ghdl/setup-ghdl@v1
+      if: ${{ inputs.install_ghdl_mcode != 'false' }}
+      with:
+        version: nightly
+        backend: mcode
+        investigate: true
+    - name: Install additional ubuntu packages
+      if: ${{ inputs.additional_system_packages != '' }}
+      shell: bash
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y ${{ inputs.additional_system_packages }}
+    - name: Install additional python packages
+      if: ${{ inputs.additional_python_packages != '' }}
+      shell: bash
+      run: |
+        uv add ${{ inputs.additional_python_packages }}
+    - name: Install FABulous with dev dependencies
+      shell: bash
+      run: |
+        uv sync --dev --locked --all-extras
+        uv pip install -e .
+    - name: Set PATH
+      shell: bash
+      run: |
+        echo "/home/runner/work/FABulous/FABulous/install/bin:/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin:$PATH" >> "$GITHUB_PATH"

fabulous_fpga-2.0.0b1/.github/copilot-instruction.md

@@ -0,0 +1,7 @@
+We use pytest as our testing infrastructure 
+
+We use numpy style documentation
+
+We use loguru for logging
+
+

fabulous_fpga-2.0.0b1/.github/workflows/backwards-compatibility.yml

@@ -0,0 +1,40 @@
+name: Test fabric generation against base branch
+
+on:
+  pull_request:
+    paths:
+      - 'FABulous/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - '.github/workflows/backwards-compatibility.yml'
+      - '.github/actions/**'
+
+jobs:
+  run_sim_makefile_on_base_project:
+    name: Run fabric generator flow and simulation with FABulous makefile against base branch
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - name: Verilog
+            type: verilog 
+          - name: VHDL
+            type: vhdl
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.base_ref }} 
+      - uses: ./.github/actions/prepare_FABulous_container
+      - name: generate old project
+        run: |
+          uv run FABulous -c /tmp/demo_${{ matrix.type }} -w ${{ matrix.type }}
+
+      - uses: actions/checkout@v5
+      - uses: ./.github/actions/prepare_FABulous_container
+      - name: Run fabric generator flow and simulation with FABulous makefile
+        id: run_simulation
+        continue-on-error: true
+        run: |
+          cd /tmp/demo_${{ matrix.type }}/Test
+          make FAB_sim

fabulous_fpga-2.0.0b1/.github/workflows/nix-env.yml

@@ -0,0 +1,59 @@
+name: Nix environment CI
+
+on:
+  push:
+    paths:
+      - "flake.nix"
+      - "*.lock"
+      - "nix/**"
+      - ".github/workflows/nix-env.yml"
+  pull_request:
+    paths:
+      - "flake.nix"
+      - "*.lock"
+      - "nix/**"
+      - ".github/workflows/nix-env.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  nix-smoke-test:
+    name: Smoke test (Nix ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, ubuntu-22.04]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: nixbuild/nix-quick-install-action@v34
+        with:
+          nix_version: "2.31.2"
+          nix_conf: |
+            substituters = https://cache.nixos.org https://nix-cache.fossi-foundation.org
+            extra-trusted-public-keys = nix-cache.fossi-foundation.org:3+K59iFwXqKsL7BNu6Guy0v+uTlwsxYQxjspXzqLYQs=
+
+      # - name: Enable magic Nix cache
+      #   uses: DeterminateSystems/magic-nix-cache-action@v8
+
+      - name: Print Nix version
+        run: nix --version
+
+      - name: Build default package (smoke)
+        run: nix build
+
+      - name: DevShell smoke test
+        run: |
+          nix develop --command bash -c "which FABulous"
+          nix develop --command bash -c "FABulous --version"
+          nix develop --command bash -c "which openroad"
+          nix develop --command bash -c "openroad -version"

fabulous_fpga-2.0.0b1/.github/workflows/pre-commit-hooks.yml

@@ -0,0 +1,20 @@
+name: Run pre-commit hooks
+
+on: [push, pull_request]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+    - name: Install the project
+      run: |
+        echo "UV_SYSTEM_PYTHON=1" >> $GITHUB_ENV
+        uv sync --locked --all-extras --dev
+
+    - name: run pre-commit
+      run: |
+        uv run pre-commit install
+        SKIP=no-commit-to-branch uv run pre-commit run --show-diff-on-failure --color=always --all-files

fabulous_fpga-2.0.0b1/.github/workflows/publish_to_pypi.yml

@@ -0,0 +1,62 @@
+name: Publish FABulous to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        fetch-depth: 0
+        persist-credentials: false
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7.1.2
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+    - name: Build a binary wheel and a source tarball
+      run: uv build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI (${{ github.event.release.prerelease && 'Pre-release' || 'Stable' }})
+    needs:
+    - build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/FABulous-FPGA
+
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+    - name: Check release type
+      run: |
+        if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+          echo "📦 Publishing PRE-RELEASE to PyPI"
+          echo "Users will need to use: pip install FABulous-FPGA --pre"
+        else
+          echo "🚀 Publishing STABLE RELEASE to PyPI"
+          echo "Users can install with: pip install FABulous-FPGA"
+        fi
+
+    - name: Publish distribution to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

fabulous_fpga-2.0.0b1/.github/workflows/pytest_testing.yml

@@ -0,0 +1,261 @@
+name: Testing with pytest and cocotb
+
+on:
+  push:
+    paths:
+      - 'FABulous/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - '.github/workflows/pytest_testing.yml'
+      - '.github/actions/**'
+  pull_request:
+    paths:
+      - 'FABulous/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - '.github/workflows/pytest_testing.yml'
+      - '.github/actions/**'
+
+# copy and modified based on https://github.com/jerry-git/pytest-split/issues/20#issuecomment-2576031836
+
+jobs:
+  restore_test_durations:
+    name: Restore test durations
+    runs-on: ubuntu-latest
+    steps:
+      # It's mandatory to use the exact same path when saving/restoring cache, otherwise it won't work
+      - name: Restore test durations
+        id: restore-test-durations
+        uses: actions/cache/restore@v4
+        with:
+          path: /tmp/.test_durations_cached
+          key: tests-durations-${{ github.sha }}
+          restore-keys: |
+            tests-durations-${{ github.sha }}
+            tests-durations-
+          fail-on-cache-miss: false
+          
+      # Then we upload the restored test durations as an artifact. This way, each matrix job will download
+      # it when it starts. When a matrix job will be manually retried, it will also reuse the artifact (to
+      # retry the exact same tests, even if the cache has been updated in the meantime).
+      - name: Upload test durations
+        if: steps.restore-test-durations.outputs.cache-hit != ''
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-durations-before
+          path: /tmp/.test_durations_cached
+          include-hidden-files: true
+    outputs:
+      # This output will be used to know if we had a cache hit (exact match or not), or no cache hit at all.
+      # > cache-hit - A string value to indicate an exact match was found for the key.
+      # > If there's a cache hit, this will be 'true' or 'false' to indicate if there's an exact match for key.
+      # > If there's a cache miss, this will be an empty string.
+      restored: ${{ steps.restore-test-durations.outputs.cache-hit == '' && 'false' || 'true' }}
+
+  pytest_testing:
+    needs: restore_test_durations
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    strategy:
+      fail-fast: false
+      matrix:
+        job-index: [ 1, 2, 3, 4, 5, 6, 7, 8 ]
+    steps:
+      # These two steps will be executed only when there IS a cache hit (exact match or not). 
+      # When a matrix job is retried, it will reuse the same artifact, to execute the exact same split.
+      - uses: actions/checkout@v5
+        with: 
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Download test durations
+        if: needs.restore_test_durations.outputs.restored == 'true'
+        uses: actions/download-artifact@v4
+        with:
+          name: test-durations-before
+      - name: Use cached test durations
+        if: needs.restore_test_durations.outputs.restored == 'true'
+        run: mv .test_durations_cached .test_durations
+        
+      # This step will be executed only when there is NO cache hit.
+      # You need to commit file `.test_durations_fallback`.
+      # You can also refresh it manually from time to time to keep an up-to-date fallback
+      # (see step "Upload final test durations" below).
+      - name: Use fallback test durations
+        if: needs.restore_test_durations.outputs.restored == 'false' 
+        run: |
+          if [ -f .test_durations_fallback ]; then
+            mv .test_durations_fallback .test_durations
+          else
+            echo ".test_durations_fallback does not exist! Run with default even splits."
+          fi
+
+      - uses: ./.github/actions/prepare_FABulous_container
+        with:
+          additional_system_packages: "iverilog"
+
+      # When running pytest, we write the new test durations using options
+      # `--store-durations --clean-durations`.
+      # Option `--clean-durations` is undocumented
+      # Removes the test duration info for tests which are not present 
+      # while running the suite with '--store-durations'.
+      - name: Run pytest
+        env:
+          COVERAGE_FILE: .coverage.${{ matrix.job-index }}
+        run: |
+          echo "Running at PATH=$PATH"
+          which ghdl
+          which iverilog
+          # Ensure no stale coverage data from previous attempts (no coverage module needed)
+          rm -f .coverage* || true
+          uv run pytest \
+            --splits ${{ strategy.job-total }} --group ${{ matrix.job-index }} \
+            --store-durations --clean-durations -v -x --runslow \
+            --cov=FABulous --cov-branch --cov-config=pyproject.toml --cov-report= \
+            || {
+            exit_code=$?
+            if [ $exit_code -eq 5 ]; then
+              echo "No tests were collected (exit code 5). This is expected for some groups."
+              exit 0
+            else
+              echo "pytest failed with exit code $exit_code"
+              exit $exit_code
+            fi
+          }
+
+      - name: Show coverage data files
+        if: github.run_attempt == 1
+        run: |
+          echo "Listing coverage data files in $PWD"
+          ls -la .coverage* || true
+
+      # Each matrix job uploads its freshly updated partial test durations. We regroup them all
+      # within one final file in the "Merge all partial test durations" step below.
+      - name: Upload test durations
+        if: github.run_attempt == 1
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-durations-after-partial-${{ matrix.job-index }}
+          path: .test_durations
+          if-no-files-found: error
+          include-hidden-files: true
+
+      - name: Upload coverage data
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-after-partial-attempt-${{ github.run_attempt }}-${{ matrix.job-index }}
+          path: .coverage*
+          if-no-files-found: warn
+          include-hidden-files: true
+
+  cache_test_durations:
+    name: Cache test durations
+    needs: pytest_testing
+    if: github.run_attempt == 1 && (success() || failure())
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download all partial test durations
+        uses: actions/download-artifact@v4
+        with:
+          pattern: test-durations-after-partial-*
+          
+      # This step regroups the 8 partial files and sorts keys alphabetically:
+      - name: Merge all partial test durations
+        run: |
+          jq -s 'add' test-durations-after-partial-*/.test_durations \
+          | jq 'to_entries | sort_by(.key) | from_entries' \
+          > /tmp/.test_durations_cached
+
+      # This step uploads the final file as an artifact. You can then download it from the Github GUI,
+      # and use it to manually commit file `.test_durations_fallback` from time to time,
+      # to keep an up-to-date fallback:
+      - name: Upload final test durations
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-durations-after
+          path: /tmp/.test_durations_cached
+          if-no-files-found: error
+          include-hidden-files: true
+
+      # Finally, we cache the new test durations. This file will be restored in next CI execution
+      - name: Cache final test durations
+        uses: actions/cache/save@v4
+        with:
+          path: /tmp/.test_durations_cached
+          key: tests-durations-${{ github.sha }}
+
+  coverage_check:
+    name: Combine, publish, and check coverage
+    needs: pytest_testing
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+      pull-requests: write
+      issues: write
+    env:
+      COVERAGE_FAIL_UNDER: '70'
+    steps:
+      - uses: actions/checkout@v5
+      - name: Download all partial coverage artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-after-partial-*
+          merge-multiple: false
+
+      - name: Set up Python for coverage
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install coverage tool
+        run: |
+          python -m pip install --upgrade pip
+          pip install coverage
+
+      - name: Combine coverage and generate reports
+        env:
+          COVERAGE_FILE: .coverage
+        shell: bash
+        run: |
+          echo "Found coverage artifacts:"
+          set -e
+          files=$(find . -type f -regextype posix-extended -regex "./coverage-after-partial-.*/\.coverage(\..+)?" -print | sort || true)
+          echo "$files"
+          if [ -z "$files" ]; then
+            echo "No coverage files found. Skipping report generation."
+            exit 0
+          fi
+          echo "Combining the following coverage data files:"
+          printf '%s\n' $files
+          coverage combine $files
+          coverage xml -o coverage.xml
+          coverage html -d coverage_html
+          coverage report --skip-covered --format=markdown > code-coverage-results.md || true
+
+      - name: Upload combined coverage XML
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: error
+
+      - name: Upload combined coverage HTML
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html
+          path: coverage_html
+          if-no-files-found: error
+
+      - name: Add coverage summary to job summary
+        if: ${{ hashFiles('code-coverage-results.md') != '' }}
+        shell: bash
+        run: |
+          echo "Coverage Summary" >> "$GITHUB_STEP_SUMMARY"
+          cat code-coverage-results.md >> "$GITHUB_STEP_SUMMARY"
+      - name: Enforce coverage threshold
+        if: ${{ hashFiles('coverage.xml') != '' }}
+        shell: bash
+        run: |
+          echo "Enforcing coverage threshold: ${COVERAGE_FAIL_UNDER}%"
+          coverage report --fail-under=${COVERAGE_FAIL_UNDER}
+

fabulous_fpga-2.0.0b1/.github/workflows/release_please.yml

@@ -0,0 +1,42 @@
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+name: release-please
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/create-github-app-token@v2
+      id: app-token
+      with:
+        app-id: ${{ vars.RP_APP_ID }}
+        private-key: ${{ secrets.RP_APP_PK }}
+        owner: ${{ github.repository_owner }}
+        repositories: ${{ github.event.repository.name }}
+    - uses: googleapis/release-please-action@v4
+      id: release
+      with:
+        token: ${{ steps.app-token.outputs.token }}
+        release-type: python
+        
+    - name: tag major and minor versions
+      if: ${{ steps.release.outputs.release_created }}
+      run: |
+        git config user.name github-actions[bot]
+        git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+        git tag -d v${{ steps.release.outputs.major }} || true
+        git tag -d v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }} || true
+        git push origin :v${{ steps.release.outputs.major }} || true
+        git push origin :v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }} || true
+        git tag -a v${{ steps.release.outputs.major }} -m "Release v${{ steps.release.outputs.major }}"
+        git tag -a v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }} -m "Release v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}"
+        git push origin v${{ steps.release.outputs.major }}
+        git push origin v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}

fabulous_fpga-2.0.0b1/.gitignore

@@ -0,0 +1,14 @@
+demo*
+**/__pycache__
+*.egg-info/
+.venv
+venv
+.env
+.vscode
+oss-cad-suite
+
+# Documentation build artifacts (auto-generated in CI)
+docs/build/
+docs/source/references/*.rst
+!docs/source/references/index.rst
+docs/source/generated_doc/