diff --git a/.editorconfig b/.editorconfig index f5444d81a..572b73bd2 100644 --- a/.editorconfig +++ b/.editorconfig @@ -10,3 +10,7 @@ insert_final_newline = true indent_style = space indent_size = 2 trim_trailing_whitespace = false + +[*.yml] +indent_style = space +indent_size = 2 diff --git a/.github/actions/setup-build-env/action.yml b/.github/actions/setup-build-env/action.yml index c5a0d14ab..dfdcd88c0 100644 --- a/.github/actions/setup-build-env/action.yml +++ b/.github/actions/setup-build-env/action.yml @@ -8,13 +8,14 @@ runs: shell: bash run: | sudo apt-get update - sudo apt-get install gperf build-essential bison flex libreadline-dev gawk tcl-dev libffi-dev git graphviz xdot pkg-config python3 libboost-system-dev libboost-python-dev libboost-filesystem-dev zlib1g-dev + sudo apt-get install gperf build-essential bison flex libreadline-dev gawk tcl-dev libffi-dev git graphviz xdot pkg-config python3 libboost-system-dev libboost-python-dev libboost-filesystem-dev zlib1g-dev libbz2-dev - name: Install macOS Dependencies if: runner.os == 'macOS' shell: bash run: | - HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=1 brew install bison flex gawk libffi pkg-config bash autoconf llvm + HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=1 brew update + HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=1 brew install bison flex gawk libffi pkg-config bash autoconf llvm lld || true - name: Linux runtime environment if: runner.os == 'Linux' diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 24ae7c898..75d799fe1 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -16,7 +16,9 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 with: - submodules: true + submodules: true + persist-credentials: false + - name: Initialize CodeQL uses: github/codeql-action/init@v3 with: diff --git a/.github/workflows/extra-builds.yml b/.github/workflows/extra-builds.yml index 1a00d0163..d7ceb3fe3 100644 --- a/.github/workflows/extra-builds.yml +++ b/.github/workflows/extra-builds.yml @@ -25,7 +25,8 @@ jobs: steps: - uses: actions/checkout@v4 with: - submodules: true + submodules: true + persist-credentials: false - name: Build run: make vcxsrc YOSYS_VER=latest - uses: actions/upload-artifact@v4 @@ -35,7 +36,7 @@ jobs: vs-build: name: Visual Studio build - runs-on: windows-2019 + runs-on: windows-latest needs: [vs-prep, pre_job] if: needs.pre_job.outputs.should_skip != 'true' steps: @@ -59,7 +60,8 @@ jobs: steps: - uses: actions/checkout@v4 with: - submodules: true + submodules: true + persist-credentials: false - name: Build run: | WASI_SDK=wasi-sdk-19.0 @@ -95,6 +97,7 @@ jobs: - uses: actions/checkout@v4 with: submodules: true + persist-credentials: false - uses: cachix/install-nix-action@v26 with: install_url: https://releases.nixos.org/nix/nix-2.18.1/install diff --git a/.github/workflows/prepare-docs.yml b/.github/workflows/prepare-docs.yml index 9233e6295..fb1fab426 100644 --- a/.github/workflows/prepare-docs.yml +++ b/.github/workflows/prepare-docs.yml @@ -1,12 +1,32 @@ name: Build docs artifact with Verific -on: push +on: [push, pull_request] jobs: + check_docs_rebuild: + runs-on: ubuntu-latest + outputs: + skip_check: ${{ steps.skip_check.outputs.should_skip }} + docs_export: ${{ steps.docs_var.outputs.docs_export }} + env: + docs_export: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/docs-preview') || startsWith(github.ref, 'refs/tags/') }} + steps: + - id: skip_check + uses: fkirc/skip-duplicate-actions@v5 + with: + paths_ignore: '["**/README.md"]' + # don't cancel in case we're updating docs + cancel_others: 'false' + # only run on push *or* pull_request, not both + concurrent_skipping: ${{ env.docs_export && 'never' || 'same_content_newer'}} + - id: docs_var + run: echo "docs_export=${docs_export}" >> $GITHUB_OUTPUT + prepare-docs: # docs builds are needed for anything on main, any tagged versions, and any tag # or branch starting with docs-preview - if: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/docs-preview') || startsWith(github.ref, 'refs/tags/') }} + needs: check_docs_rebuild + if: ${{ needs.check_docs_rebuild.outputs.should_skip != 'true' }} runs-on: [self-hosted, linux, x64, fast] steps: - name: Checkout Yosys @@ -27,12 +47,12 @@ jobs: echo "ENABLE_VERIFIC_LIBERTY := 1" >> Makefile.conf echo "ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS := 1" >> Makefile.conf echo "ENABLE_CCACHE := 1" >> Makefile.conf - make -j${{ env.procs }} ENABLE_LTO=1 + make -j$procs ENABLE_LTO=1 - name: Prepare docs shell: bash run: - make docs/prep TARGETS= EXTRA_TARGETS= + make docs/prep -j$procs TARGETS= EXTRA_TARGETS= - name: Upload artifact uses: actions/upload-artifact@v4 @@ -44,7 +64,18 @@ jobs: docs/source/_images docs/source/code_examples + - name: Install doc prereqs + shell: bash + run: | + make docs/reqs + + - name: Test build docs + shell: bash + run: | + make -C docs html -j$procs TARGETS= EXTRA_TARGETS= + - name: Trigger RTDs build + if: ${{ needs.check_docs_rebuild.outputs.docs_export == 'true' }} uses: dfm/rtds-action@v1.1.0 with: webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }} diff --git a/.github/workflows/source-vendor.yml b/.github/workflows/source-vendor.yml new file mode 100644 index 000000000..dc9480ef6 --- /dev/null +++ b/.github/workflows/source-vendor.yml @@ -0,0 +1,34 @@ +name: Create source archive with vendored dependencies + +on: [push, workflow_dispatch] + +jobs: + vendor-sources: + runs-on: ubuntu-latest + steps: + - name: Checkout repository with submodules + uses: actions/checkout@v4 + with: + submodules: 'recursive' + persist-credentials: false + + - name: Create clean tarball + run: | + git archive --format=tar HEAD -o yosys-src-vendored.tar + git submodule foreach ' + git archive --format=tar --prefix="${sm_path}/" HEAD --output=${toplevel}/vendor-${name}.tar + ' + + # 2008 bug https://lists.gnu.org/archive/html/bug-tar/2008-08/msg00002.html + for file in vendor-*.tar; do + tar --concatenate --file=yosys-src-vendored.tar "$file" + done + + gzip yosys-src-vendored.tar + + - name: Store tarball artifact + uses: actions/upload-artifact@v4 + with: + name: vendored-sources + path: yosys-src-vendored.tar.gz + retention-days: 1 diff --git a/.github/workflows/test-build.yml b/.github/workflows/test-build.yml index 0eb2c65c5..22d3a94f8 100644 --- a/.github/workflows/test-build.yml +++ b/.github/workflows/test-build.yml @@ -40,12 +40,14 @@ jobs: strategy: matrix: os: [ubuntu-latest, macos-latest] + sanitizer: [undefined, address] fail-fast: false steps: - name: Checkout Yosys uses: actions/checkout@v4 with: submodules: true + persist-credentials: false - name: Setup environment uses: ./.github/actions/setup-build-env @@ -56,6 +58,7 @@ jobs: mkdir build cd build make -f ../Makefile config-$CC + echo 'SANITIZER = ${{ matrix.sanitizer }}' >> Makefile.conf make -f ../Makefile -j$procs ENABLE_LTO=1 - name: Log yosys-config output @@ -71,7 +74,7 @@ jobs: - name: Store build artifact uses: actions/upload-artifact@v4 with: - name: build-${{ matrix.os }} + name: build-${{ matrix.os }}-${{ matrix.sanitizer }} path: build.tar retention-days: 1 @@ -82,13 +85,18 @@ jobs: if: needs.pre_job.outputs.should_skip != 'true' env: CC: clang + ASAN_OPTIONS: halt_on_error=1 + UBSAN_OPTIONS: halt_on_error=1 strategy: matrix: os: [ubuntu-latest, macos-latest] + sanitizer: [undefined, address] fail-fast: false steps: - name: Checkout Yosys uses: actions/checkout@v4 + with: + persist-credentials: false - name: Setup environment uses: ./.github/actions/setup-build-env @@ -100,12 +108,22 @@ jobs: cd iverilog echo "IVERILOG_GIT=$(git rev-parse HEAD)" >> $GITHUB_ENV + - name: Get vcd2fst + shell: bash + run: | + git clone https://github.com/mmicko/libwave.git + mkdir -p ${{ github.workspace }}/.local/ + cd libwave + cmake . -DCMAKE_INSTALL_PREFIX=${{ github.workspace }}/.local + make -j$procs + make install + - name: Cache iverilog id: cache-iverilog uses: actions/cache@v4 with: path: .local/ - key: ${{ matrix.os }}-${{ env.IVERILOG_GIT }} + key: ${{ matrix.os }}-${IVERILOG_GIT} - name: Build iverilog if: steps.cache-iverilog.outputs.cache-hit != 'true' @@ -121,7 +139,7 @@ jobs: - name: Download build artifact uses: actions/download-artifact@v4 with: - name: build-${{ matrix.os }} + name: build-${{ matrix.os }}-${{ matrix.sanitizer }} - name: Uncompress build shell: bash @@ -153,10 +171,13 @@ jobs: strategy: matrix: os: [ubuntu-latest] + sanitizer: [undefined, address] fail-fast: false steps: - name: Checkout Yosys uses: actions/checkout@v4 + with: + persist-credentials: false - name: Setup environment uses: ./.github/actions/setup-build-env @@ -164,7 +185,7 @@ jobs: - name: Download build artifact uses: actions/download-artifact@v4 with: - name: build-${{ matrix.os }} + name: build-${{ matrix.os }}-${{ matrix.sanitizer }} - name: Uncompress build shell: bash @@ -178,4 +199,47 @@ jobs: - name: Run tests shell: bash run: | - make -C docs test -j${{ env.procs }} + make -C docs test -j$procs + + test-docs-build: + name: Try build docs + runs-on: [self-hosted, linux, x64, fast] + needs: [pre_docs_job] + if: needs.pre_docs_job.outputs.should_skip != 'true' + strategy: + matrix: + docs-target: [html, latexpdf] + fail-fast: false + steps: + - name: Checkout Yosys + uses: actions/checkout@v4 + with: + submodules: true + persist-credentials: false + + - name: Runtime environment + run: | + echo "procs=$(nproc)" >> $GITHUB_ENV + + - name: Build Yosys + run: | + make config-clang + echo "ENABLE_CCACHE := 1" >> Makefile.conf + make -j$procs + + - name: Install doc prereqs + shell: bash + run: | + make docs/reqs + + - name: Build docs + shell: bash + run: | + make docs DOC_TARGET=${{ matrix.docs-target }} -j$procs + + - name: Store docs build artifact + uses: actions/upload-artifact@v4 + with: + name: docs-build-${{ matrix.docs-target }} + path: docs/build/ + retention-days: 7 diff --git a/.github/workflows/test-compile.yml b/.github/workflows/test-compile.yml index 089e65ca7..7a706e69a 100644 --- a/.github/workflows/test-compile.yml +++ b/.github/workflows/test-compile.yml @@ -30,24 +30,22 @@ jobs: - ubuntu-latest compiler: # oldest supported - - 'clang-14' + - 'clang-10' - 'gcc-10' - # newest - - 'clang' - - 'gcc' + # newest, make sure to update maximum standard step to match + - 'clang-19' + - 'gcc-13' include: # macOS - os: macos-13 compiler: 'clang' - # oldest clang not available on ubuntu-latest - - os: ubuntu-20.04 - compiler: 'clang-10' fail-fast: false steps: - name: Checkout Yosys uses: actions/checkout@v4 with: submodules: true + persist-credentials: false - name: Setup environment uses: ./.github/actions/setup-build-env @@ -72,7 +70,7 @@ jobs: # maximum standard, only on newest compilers - name: Build C++20 - if: ${{ matrix.compiler == 'clang' || matrix.compiler == 'gcc'}} + if: ${{ matrix.compiler == 'clang-19' || matrix.compiler == 'gcc-13' }} shell: bash run: | make config-$CC_SHORT diff --git a/.github/workflows/test-verific.yml b/.github/workflows/test-verific.yml index 98b05e8dd..013c9f8ca 100644 --- a/.github/workflows/test-verific.yml +++ b/.github/workflows/test-verific.yml @@ -40,7 +40,7 @@ jobs: echo "ENABLE_VERIFIC_YOSYSHQ_EXTENSIONS := 1" >> Makefile.conf echo "ENABLE_CCACHE := 1" >> Makefile.conf echo "ENABLE_FUNCTIONAL_TESTS := 1" >> Makefile.conf - make -j${{ env.procs }} ENABLE_LTO=1 + make -j$procs ENABLE_LTO=1 - name: Install Yosys run: | @@ -51,6 +51,7 @@ jobs: with: repository: 'YosysHQ/sby' path: 'sby' + persist-credentials: false - name: Build SBY run: | @@ -58,7 +59,7 @@ jobs: - name: Run Yosys tests run: | - make -j${{ env.procs }} test + make -j$procs test - name: Run Verific specific Yosys tests run: | diff --git a/.github/workflows/update-flake-lock.yml b/.github/workflows/update-flake-lock.yml index c7aa6ecab..de7ef04d6 100644 --- a/.github/workflows/update-flake-lock.yml +++ b/.github/workflows/update-flake-lock.yml @@ -10,6 +10,8 @@ jobs: steps: - name: Checkout repository uses: actions/checkout@v4 + with: + persist-credentials: false - name: Install Nix uses: DeterminateSystems/nix-installer-action@main - name: Update flake.lock diff --git a/.github/workflows/version.yml b/.github/workflows/version.yml index f73c68bdf..26dcba4a4 100644 --- a/.github/workflows/version.yml +++ b/.github/workflows/version.yml @@ -14,6 +14,7 @@ jobs: with: fetch-depth: 0 submodules: true + persist-credentials: false - name: Take last commit id: log run: echo "message=$(git log --no-merges -1 --oneline)" >> $GITHUB_OUTPUT diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml new file mode 100644 index 000000000..b01ce6b3a --- /dev/null +++ b/.github/workflows/wheels.yml @@ -0,0 +1,137 @@ +name: Build Wheels for PyPI + +# run every Sunday at 10 AM +on: + workflow_dispatch: + schedule: + - cron: '0 10 * * 0' + +jobs: + build_wheels: + strategy: + fail-fast: false + matrix: + os: [ + { + name: "Ubuntu 22.04", + family: "linux", + runner: "ubuntu-22.04", + archs: "x86_64", + }, + { + name: "Ubuntu 22.04", + family: "linux", + runner: "ubuntu-22.04-arm", + archs: "aarch64", + }, + { + name: "macOS 13", + family: "macos", + runner: "macos-13", + archs: "x86_64", + }, + { + name: "macOS 14", + family: "macos", + runner: "macos-14", + archs: "arm64", + }, + ## Windows is disabled because of an issue with compiling FFI as + ## under MinGW in the GitHub Actions environment (SHELL variable has + ## whitespace.) + # { + # name: "Windows Server 2019", + # family: "windows", + # runner: "windows-2019", + # archs: "AMD64", + # }, + ] + name: Build Wheels | ${{ matrix.os.name }} | ${{ matrix.os.archs }} + runs-on: ${{ matrix.os.runner }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + submodules: true + persist-credentials: false + - if: ${{ matrix.os.family == 'linux' }} + name: "[Linux] Set up QEMU" + uses: docker/setup-qemu-action@v3 + - uses: actions/setup-python@v5 + - name: Get Boost Source + shell: bash + run: | + mkdir -p boost + curl -L https://github.com/boostorg/boost/releases/download/boost-1.86.0/boost-1.86.0-b2-nodocs.tar.gz | tar --strip-components=1 -xzC boost + - name: Get FFI + shell: bash + run: | + mkdir -p ffi + curl -L https://github.com/libffi/libffi/releases/download/v3.4.6/libffi-3.4.6.tar.gz | tar --strip-components=1 -xzC ffi + ## Software installed by default in GitHub Action Runner VMs: + ## https://github.com/actions/runner-images + - if: ${{ matrix.os.family == 'macos' }} + name: "[macOS] Flex/Bison" + run: | + brew install flex bison + echo "PATH=$(brew --prefix flex)/bin:$PATH" >> $GITHUB_ENV + echo "PATH=$(brew --prefix bison)/bin:$PATH" >> $GITHUB_ENV + - if: ${{ matrix.os.family == 'windows' }} + name: "[Windows] Flex/Bison" + run: | + choco install winflexbison3 + - if: ${{ matrix.os.family == 'macos' && matrix.os.archs == 'arm64' }} + name: "[macOS/arm64] Install Python 3.8 (see: https://cibuildwheel.pypa.io/en/stable/faq/#macos-building-cpython-38-wheels-on-arm64)" + uses: actions/setup-python@v5 + with: + python-version: 3.8 + - name: Build wheels + uses: pypa/cibuildwheel@v2.21.1 + env: + # * APIs not supported by PyPy + # * Musllinux disabled because it increases build time from 48m to ~3h + CIBW_SKIP: > + pp* + *musllinux* + CIBW_ARCHS: ${{ matrix.os.archs }} + CIBW_BUILD_VERBOSITY: "1" + # manylinux2014 (default) does not have a modern enough C++ compiler for Yosys + CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28 + CIBW_MANYLINUX_AARCH64_IMAGE: manylinux_2_28 + CIBW_BEFORE_ALL: bash ./.github/workflows/wheels/cibw_before_all.sh + CIBW_ENVIRONMENT: > + CXXFLAGS=-I./boost/pfx/include + LINKFLAGS=-L./boost/pfx/lib + PKG_CONFIG_PATH=./ffi/pfx/lib/pkgconfig + makeFlags='BOOST_PYTHON_LIB=./boost/pfx/lib/libboost_python*.a' + CIBW_ENVIRONMENT_MACOS: > + CXXFLAGS=-I./boost/pfx/include + LINKFLAGS=-L./boost/pfx/lib + PKG_CONFIG_PATH=./ffi/pfx/lib/pkgconfig + MACOSX_DEPLOYMENT_TARGET=11 + makeFlags='BOOST_PYTHON_LIB=./boost/pfx/lib/libboost_python*.a CONFIG=clang' + CIBW_BEFORE_BUILD: bash ./.github/workflows/wheels/cibw_before_build.sh + CIBW_TEST_COMMAND: python3 {project}/tests/arch/ecp5/add_sub.py + - uses: actions/upload-artifact@v4 + with: + name: python-wheels-${{ matrix.os.runner }} + path: ./wheelhouse/*.whl + upload_wheels: + name: Upload Wheels + runs-on: ubuntu-latest + needs: build_wheels + steps: + - uses: actions/download-artifact@v4 + with: + path: "." + pattern: python-wheels-* + merge-multiple: true + - run: | + ls + mkdir -p ./dist + mv *.whl ./dist + - name: Publish + uses: pypa/gh-action-pypi-publish@release/v1 + with: + password: ${{ secrets.PYPI_TOKEN }} + repository-url: ${{ vars.PYPI_INDEX || 'https://upload.pypi.org/legacy/' }} diff --git a/.github/workflows/wheels/_run_cibw_linux.py b/.github/workflows/wheels/_run_cibw_linux.py new file mode 100644 index 000000000..894470a5a --- /dev/null +++ b/.github/workflows/wheels/_run_cibw_linux.py @@ -0,0 +1,44 @@ +#!/usr/bin/env python3 +# Copyright (C) 2024 Efabless Corporation +# +# Permission to use, copy, modify, and/or distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +""" +This runs the cibuildwheel step from the wheels workflow locally. +""" + +import os +import yaml +import platform +import subprocess + +__dir__ = os.path.dirname(os.path.abspath(__file__)) + + +workflow = yaml.safe_load(open(os.path.join(os.path.dirname(__dir__), "wheels.yml"))) + +env = os.environ.copy() + +steps = workflow["jobs"]["build_wheels"]["steps"] +cibw_step = None +for step in steps: + if (step.get("uses") or "").startswith("pypa/cibuildwheel"): + cibw_step = step + break + +for key, value in cibw_step["env"].items(): + if key.endswith("WIN") or key.endswith("MAC"): + continue + env[key] = value + +env["CIBW_ARCHS"] = os.getenv("CIBW_ARCHS") or platform.machine() +subprocess.check_call(["cibuildwheel"], env=env) diff --git a/.github/workflows/wheels/cibw_before_all.sh b/.github/workflows/wheels/cibw_before_all.sh new file mode 100644 index 000000000..fbb8dcad8 --- /dev/null +++ b/.github/workflows/wheels/cibw_before_all.sh @@ -0,0 +1,23 @@ +set -e +set -x + +# Build-time dependencies +## Linux Docker Images +if command -v yum &> /dev/null; then + yum install -y flex bison +fi + +if command -v apk &> /dev/null; then + apk add flex bison +fi + +## macOS/Windows -- installed in GitHub Action itself, not container + +# Build Static FFI (platform-dependent but not Python version dependent) +cd ffi +## Ultimate libyosys.so will be shared, so we need fPIC for the static libraries +CFLAGS=-fPIC CXXFLAGS=-fPIC ./configure --prefix=$PWD/pfx +## Without this, SHELL has a space in its path which breaks the makefile +make install -j$(getconf _NPROCESSORS_ONLN 2>/dev/null || sysctl -n hw.ncpu) +## Forces static library to be used in all situations +sed -i.bak 's@-L${toolexeclibdir} -lffi@${toolexeclibdir}/libffi.a@' ./pfx/lib/pkgconfig/libffi.pc diff --git a/.github/workflows/wheels/cibw_before_build.sh b/.github/workflows/wheels/cibw_before_build.sh new file mode 100644 index 000000000..018b0e0df --- /dev/null +++ b/.github/workflows/wheels/cibw_before_build.sh @@ -0,0 +1,34 @@ +set -e +set -x + +# Don't use objects from previous compiles on Windows/macOS +make clean + +# DEBUG: show python3 and python3-config outputs +if [ "$(uname)" != "Linux" ]; then + # https://github.com/pypa/cibuildwheel/issues/2021 + ln -s $(dirname $(readlink -f $(which python3)))/python3-config $(dirname $(which python3))/python3-config +fi +python3 --version +python3-config --includes + +# Build boost +cd ./boost +## Delete the artefacts from previous builds (if any) +rm -rf ./pfx +## Bootstrap bjam +./bootstrap.sh --prefix=./pfx +## Build Boost against current version of Python, only for +## static linkage (Boost is statically linked because system boost packages +## wildly vary in versions, including the libboost_python3 version) +./b2\ + -j$(getconf _NPROCESSORS_ONLN 2>/dev/null || sysctl -n hw.ncpu)\ + --prefix=./pfx\ + --with-filesystem\ + --with-system\ + --with-python\ + cxxflags="$(python3-config --includes) -std=c++17 -fPIC"\ + cflags="$(python3-config --includes) -fPIC"\ + link=static\ + variant=release\ + install diff --git a/.gitignore b/.gitignore index e82343e89..3b77edf1f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,24 +1,19 @@ +## user config +/Makefile.conf + +## build artifacts +# compiler intermediate files *.o *.d *.dwo -.*.swp *.gch *.gcda *.gcno -*~ -__pycache__ -/.cproject -/.project -/.settings -/qtcreator.files -/qtcreator.includes -/qtcreator.config -/qtcreator.creator -/qtcreator.creator.user -/coverage.info -/coverage_html -/Makefile.conf -/viz.js +*.so.dSYM/ + +# compiler output files +/kernel/version_*.cc +/share /yosys /yosys.exe /yosys.js @@ -34,15 +29,50 @@ __pycache__ /yosys-witness-script.py /yosys-filterlib /yosys-filterlib.exe -/kernel/*.pyh -/kernel/python_wrappers.cc -/kernel/version_*.cc -/share /yosys-win32-mxebin-* /yosys-win32-vcxsrc-* /yosysjs-* /libyosys.so + +# build directories /tests/unit/bintest/ /tests/unit/objtest/ /tests/ystests -/result \ No newline at end of file +/build +/result +/dist + +# pyosys +/kernel/*.pyh +/kernel/python_wrappers.cc +/boost +/ffi +/venv +/*.whl +/*.egg-info + +# yosysjs dependency +/viz.js + +# other +/coverage.info +/coverage_html + + +# these really belong in global gitignore since they're not specific to this project but rather to user tool choice +# but too many people don't have a global gitignore configured: +# https://docs.github.com/en/get-started/git-basics/ignoring-files#configuring-ignored-files-for-all-repositories-on-your-computer +__pycache__ +*~ +.*.swp +/.cache +/.vscode +/.cproject +/.project +/.settings +/qtcreator.files +/qtcreator.includes +/qtcreator.config +/qtcreator.creator +/qtcreator.creator.user +/compile_commands.json diff --git a/.gitmodules b/.gitmodules index d88d4b1e5..9f18be11e 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,7 @@ [submodule "abc"] path = abc url = https://github.com/YosysHQ/abc +# Don't use paths as names to avoid git archive problems +[submodule "cxxopts"] + path = libs/cxxopts + url = https://github.com/jarro2783/cxxopts diff --git a/.mailmap b/.mailmap index 78afe1b6c..2d9f424d4 100644 --- a/.mailmap +++ b/.mailmap @@ -1,6 +1,6 @@ -Marcelina Kościelnicka -Marcelina Kościelnicka -Marcelina Kościelnicka +Wanda Phinode +Wanda Phinode +Wanda Phinode Claire Xenia Wolf Claire Xenia Wolf Claire Xenia Wolf diff --git a/Brewfile b/Brewfile index 18e4e2917..3696e40b0 100644 --- a/Brewfile +++ b/Brewfile @@ -11,3 +11,4 @@ brew "xdot" brew "bash" brew "boost-python3" brew "llvm" +brew "lld" diff --git a/CHANGELOG b/CHANGELOG index 03bf5ac57..d8f2f8804 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -2,9 +2,166 @@ List of major changes and improvements between releases ======================================================= -Yosys 0.45 .. Yosys 0.46-dev +Yosys 0.55 .. Yosys 0.56-dev -------------------------- +Yosys 0.54 .. Yosys 0.55 +-------------------------- + * Various + - read_verilog: Implemented SystemVerilog unique/priority if. + - "attrmap" pass is able to alter memory attributes. + - verific: Support SVA followed-by operator in cover mode. + +Yosys 0.53 .. Yosys 0.54 +-------------------------- + * New commands and options + - Added "-genlib" option to "abc_new" and "abc9_exe" passes. + - Added "-verbose" and "-quiet" options to "libcache" pass. + - Added "-no-sort" option to "write_aiger" pass. + + * Various + - Added "muldiv_c" peepopt. + - Accept (and ignore) SystemVerilog unique/priority if. + - "read_verilog" copy inout ports in and out of functions/tasks. + - Enable single-bit vector wires in RTLIL. + + * Xilinx support + - Single-port URAM mapping to support memories 2048 x 144b + +Yosys 0.52 .. Yosys 0.53 +-------------------------- + * New commands and options + - Added "constmap" pass for technology mapping of coarse constant value. + - Added "timeest" pass to estimate the critical path in clock domain. + - Added "-blackbox" option to "cutpoint" pass to cut all instances of + blackboxes. + - Added "-noscopeinfo" option to "cutpoint" pass. + - Added "-nocleanup" option to "flatten" pass to prevent removal of + unused submodules. + - Added "-declockgate" option to "formalff" pass that turns clock + gating into clock enables. + + * Various + - Added "$scopeinfo" cells to preserve information during "cutpoint" pass. + - Added dataflow tracking documentation. + - share: Restrict activation patterns to potentially relevant signal. + - liberty: More robust parsing. + - verific: bit blast RAM if using mem2reg attribute. + +Yosys 0.51 .. Yosys 0.52 +-------------------------- + * New commands and options + - Added "-pattern-limit" option to "share" pass to limit analysis effort. + - Added "libcache" pass to control caching of technology library + data parsed from liberty files. + - Added "read_verilog_file_list" to parse verilog file list. + + * Various + - Added $macc_v2 cell. + - Improve lexer performance and zlib support for "read_liberty". + - opt_expr: optimize pow of 2 cells. + + +Yosys 0.50 .. Yosys 0.51 +-------------------------- + * New commands and options + - Added "abstract" pass to allow reducing and never increasing + the constraints on a circuit's behavior in a formal verification setting. + + * Various + - "splitcells" pass now splits "aldff" cells. + - FunctionalIR documentation + + * QuickLogic support + - Added IOFF inference for qlf_k6n10f + + * Intel support + - Fixed RAM and DSP support. + - Overall performance improvement for "synth_intel". + +Yosys 0.49 .. Yosys 0.50 +-------------------------- + * Various + - "write_verilog" emits "$check" cell names as labels. + +Yosys 0.48 .. Yosys 0.49 +-------------------------- + * Various + - "$scopeinfo" cells are now part of JSON export by default. + - Added option to specify hierarchical separator for "flatten". + - Improved "wreduce" to handle more cases of operator size reduction. + - Updated hashing interface, see docs/source/yosys_internals/hashing.rst + for breaking API changes. + + * New commands and options + - Added "-noscopeinfo" option to "json" and "write_json" pass. + +Yosys 0.47 .. Yosys 0.48 +-------------------------- + * Various + - Removed "read_ilang" deprecated pass. + - Enhanced boxing features in the experimental "abc_new" command. + - Added new Tcl methods for design inspection. + - Added clock enable inference to "dfflibmap". + - Added a Han-Carlson and Sklansky option for $lcu mapping. + + * New commands and options + - Added "-nopeepopt" option to "clk2fflogic" pass. + - Added "-liberty" and "-dont_use" options to "clockgate" pass. + - Added "-ignore_buses" option to "read_liberty" pass. + - Added "-dont_map" option to "techmap" pass. + - Added "-selected" option to "write_json" pass. + - Added "wrapcell" command for creating wrapper modules + around selected cells. + - Added "portarcs" command for deriving propagation timing arcs. + - Added "setenv" command for setting environment variables. + + * Gowin support + - Added "-family" option to "synth_gowin" pass. + - Cell definitions split by family. + + * Verific support + - Improved blackbox support. + +Yosys 0.46 .. Yosys 0.47 +-------------------------- + * Various + - Added cxxopts library for handling command line arguments. + - Added docs generation from cells help output. + + * New commands and options + - Added "-json" option to "synth_xilinx" pass. + - Added "-derive_luts" option to "cellmatch" pass. + - Added "t:@" syntax to "select" pass. + - Added "-list-mod" option to "select" pass. + - Removed deprecated "qwp" pass. + + * Verific support + - Initial state handling for VHDL assertions. + +Yosys 0.45 .. Yosys 0.46 +-------------------------- + * Various + - Added new "functional backend" infrastructure with three example + backends (C++, SMTLIB and Rosette). + - Added new coarse-grain buffer cell type "$buf" to RTLIL. + - Added "-y" command line option to execute a Python script with + libyosys available as a built-in module. + - Added support for casting to type in Verilog frontend. + + * New commands and options + - Added "clockgate" pass for automatic clock gating cell insertion. + - Added "bufnorm" experimental pass to convert design into + buffered-normalized form. + - Added experimental "aiger2" and "xaiger2" backends, and an + experimental "abc_new" command + - Added "-force-detailed-loop-check" option to "check" pass. + - Added "-unit_delay" option to "read_liberty" pass. + + * Verific support + - Added left and right bound properties to wires when using + specific VHDL types. + Yosys 0.44 .. Yosys 0.45 -------------------------- * Various diff --git a/CODEOWNERS b/CODEOWNERS index 879bb8dee..ef8c803ed 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -20,6 +20,7 @@ passes/opt/opt_lut.cc @whitequark passes/techmap/abc9*.cc @eddiehung @Ravenslofty backends/aiger/xaiger.cc @eddiehung docs/ @KrystalDelusion +docs/source/using_yosys/synthesis/abc.rst @KrystalDelusion @Ravenslofty .github/workflows/*.yml @mmicko ## External Contributors diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..ad2910630 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,128 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at contact@yosyshq.com and/or +claire@clairexen.net. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..6c4376cc4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,73 @@ +# Introduction + +Thanks for thinking about contributing to the Yosys project. If this is your +first time contributing to an open source project, please take a look at the +following guide: +https://opensource.guide/how-to-contribute/#orienting-yourself-to-a-new-project. + +Information about the Yosys coding style is available on our Read the Docs: +https://yosys.readthedocs.io/en/latest/yosys_internals/extending_yosys/contributing.html. + +# Using the issue tracker + +The [issue tracker](https://github.com/YosysHQ/yosys/issues) is used for +tracking bugs or other problems with Yosys or its documentation. It is also the +place to go for requesting new features. +When [creating a new issue](https://github.com/YosysHQ/yosys/issues/new/choose), +we have a few templates available. Please make use of these! It will make it +much easier for someone to respond and help. + +### Bug reports + +Before you submit an issue, please have a search of the existing issues in case +one already exists. Making sure that you have a minimal, complete and +verifiable example (MVCE) is a great way to quickly check an existing issue +against a new one. Stack overflow has a guide on [how to create an +MVCE](https://stackoverflow.com/help/minimal-reproducible-example). The +[`bugpoint` +command](https://yosyshq.readthedocs.io/projects/yosys/en/latest/cmd/bugpoint.html) +in Yosys can be helpful for this process. + + +# Using pull requests + +If you are working on something to add to Yosys, or fix something that isn't +working quite right, make a [PR](https://github.com/YosysHQ/yosys/pulls)! An +open PR, even as a draft, tells everyone that you're working on it and they +don't have to. It can also be a useful way to solicit feedback on in-progress +changes. See below to find the best way to [ask us +questions](#asking-questions). + +In general, all changes to the code are done as a PR, with [Continuous +Integration (CI)](https://github.com/YosysHQ/yosys/actions) tools that +automatically run the full suite of tests compiling and running Yosys. Please +make use of this! If you're adding a feature: add a test! Not only does it +verify that your feature is working as expected, but it can also be a handy way +for people to see how the feature is used. If you're fixing a bug: add a test! +If you can, do this first; it's okay if the test starts off failing - you +already know there is a bug. CI also helps to make sure that your changes still +work under a range of compilers, settings, and targets. + + +### Labels + +We use [labels](https://github.com/YosysHQ/yosys/labels) to help categorise +issues and PRs. If a label seems relevant to your work, please do add it; this +also includes the labels beggining with 'status-'. The 'merge-' labels are used +by maintainers for tracking and communicating which PRs are ready and pending +merge; please do not use these labels if you are not a maintainer. + + +# Asking questions + +If you have a question about how to use Yosys, please ask on our [discussions +page](https://github.com/YosysHQ/yosys/discussions) or in our [community +slack](https://join.slack.com/t/yosyshq/shared_invite/zt-1aopkns2q-EiQ97BeQDt_pwvE41sGSuA). +The slack is also a great place to ask questions about developing or +contributing to Yosys. + +We have open dev 'jour fixe' (JF) meetings where developers from YosysHQ and the +community come together to discuss open issues and PRs. This is also a good +place to talk to us about how to implement larger PRs. Please join the +community slack if you would like to join the next meeting, the link is +available in the description of the #devel-discuss channel. diff --git a/COPYING b/COPYING index e8b123be2..2d962dddc 100644 --- a/COPYING +++ b/COPYING @@ -1,6 +1,6 @@ ISC License -Copyright (C) 2012 - 2020 Claire Xenia Wolf +Copyright (C) 2012 - 2025 Claire Xenia Wolf Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above diff --git a/Makefile b/Makefile index b841c2fa6..d509b9234 100644 --- a/Makefile +++ b/Makefile @@ -2,9 +2,7 @@ CONFIG := none # CONFIG := clang # CONFIG := gcc -# CONFIG := afl-gcc # CONFIG := wasi -# CONFIG := mxe # CONFIG := msys2-32 # CONFIG := msys2-64 @@ -104,6 +102,7 @@ LIBS := $(LIBS) -lstdc++ -lm PLUGIN_LINKFLAGS := PLUGIN_LIBS := EXE_LINKFLAGS := +EXE_LIBS := ifeq ($(OS), MINGW) EXE_LINKFLAGS := -Wl,--export-all-symbols -Wl,--out-implib,libyosys_exe.a PLUGIN_LINKFLAGS += -L"$(LIBDIR)" @@ -116,16 +115,23 @@ BISON ?= bison STRIP ?= strip AWK ?= awk +ifneq ($(shell :; command -v rsync),) +RSYNC_CP ?= rsync -rc +else +RSYNC_CP ?= cp -ru +endif + ifeq ($(OS), Darwin) PLUGIN_LINKFLAGS += -undefined dynamic_lookup +LINKFLAGS += -rdynamic # homebrew search paths ifneq ($(shell :; command -v brew),) BREW_PREFIX := $(shell brew --prefix)/opt $(info $$BREW_PREFIX is [${BREW_PREFIX}]) ifeq ($(ENABLE_PYOSYS),1) -CXXFLAGS += -I$(BREW_PREFIX)/boost/include/boost -LINKFLAGS += -L$(BREW_PREFIX)/boost/lib +CXXFLAGS += -I$(BREW_PREFIX)/boost/include +LINKFLAGS += -L$(BREW_PREFIX)/boost/lib -L$(BREW_PREFIX)/boost-python3/lib endif CXXFLAGS += -I$(BREW_PREFIX)/readline/include LINKFLAGS += -L$(BREW_PREFIX)/readline/lib @@ -154,7 +160,14 @@ ifeq ($(OS), Haiku) CXXFLAGS += -D_DEFAULT_SOURCE endif -YOSYS_VER := 0.45+106 +YOSYS_VER := 0.55+146 +YOSYS_MAJOR := $(shell echo $(YOSYS_VER) | cut -d'.' -f1) +YOSYS_MINOR := $(shell echo $(YOSYS_VER) | cut -d'.' -f2 | cut -d'+' -f1) +YOSYS_COMMIT := $(shell echo $(YOSYS_VER) | cut -d'+' -f2) +CXXFLAGS += -DYOSYS_VER=\\"$(YOSYS_VER)\\" \ + -DYOSYS_MAJOR=$(YOSYS_MAJOR) \ + -DYOSYS_MINOR=$(YOSYS_MINOR) \ + -DYOSYS_COMMIT=$(YOSYS_COMMIT) # Note: We arrange for .gitcommit to contain the (short) commit hash in # tarballs generated with git-archive(1) using .gitattributes. The git repo @@ -170,7 +183,7 @@ endif OBJS = kernel/version_$(GIT_REV).o bumpversion: - sed -i "/^YOSYS_VER := / s/+[0-9][0-9]*$$/+`git log --oneline 9ed031d.. | wc -l`/;" Makefile + sed -i "/^YOSYS_VER := / s/+[0-9][0-9]*$$/+`git log --oneline 60f126c.. | wc -l`/;" Makefile ABCMKARGS = CC="$(CXX)" CXX="$(CXX)" ABC_USE_LIBSTDCXX=1 ABC_USE_NAMESPACE=abc VERBOSE=$(Q) @@ -191,17 +204,17 @@ endif include Makefile.conf endif -PYTHON_EXECUTABLE := $(shell if python3 -c ""; then echo "python3"; else echo "python"; fi) +PYTHON_EXECUTABLE ?= $(shell if python3 -c ""; then echo "python3"; else echo "python"; fi) ifeq ($(ENABLE_PYOSYS),1) PYTHON_VERSION_TESTCODE := "import sys;t='{v[0]}.{v[1]}'.format(v=list(sys.version_info[:2]));print(t)" PYTHON_VERSION := $(shell $(PYTHON_EXECUTABLE) -c ""$(PYTHON_VERSION_TESTCODE)"") PYTHON_MAJOR_VERSION := $(shell echo $(PYTHON_VERSION) | cut -f1 -d.) -ENABLE_PYTHON_CONFIG_EMBED ?= $(shell $(PYTHON_EXECUTABLE)-config --embed --libs > /dev/null && echo 1) -ifeq ($(ENABLE_PYTHON_CONFIG_EMBED),1) -PYTHON_CONFIG := $(PYTHON_EXECUTABLE)-config --embed -else PYTHON_CONFIG := $(PYTHON_EXECUTABLE)-config +PYTHON_CONFIG_FOR_EXE := $(PYTHON_CONFIG) +PYTHON_CONFIG_EMBED_AVAILABLE ?= $(shell $(PYTHON_EXECUTABLE)-config --embed --libs > /dev/null && echo 1) +ifeq ($(PYTHON_CONFIG_EMBED_AVAILABLE),1) +PYTHON_CONFIG_FOR_EXE := $(PYTHON_CONFIG) --embed endif PYTHON_DESTDIR := $(shell $(PYTHON_EXECUTABLE) -c "import site; print(site.getsitepackages()[-1]);") @@ -264,16 +277,6 @@ ifeq ($(DISABLE_ABC_THREADS),1) ABCMKARGS += "ABC_USE_NO_PTHREADS=1" endif -else ifeq ($(CONFIG),afl-gcc) -CXX = AFL_QUIET=1 AFL_HARDEN=1 afl-gcc -CXXFLAGS += -std=$(CXXSTD) $(OPT_LEVEL) -ABCMKARGS += ARCHFLAGS="-DABC_USE_STDINT_H" - -else ifeq ($(CONFIG),cygwin) -CXX = g++ -CXXFLAGS += -std=gnu++11 $(OPT_LEVEL) -ABCMKARGS += ARCHFLAGS="-DABC_USE_STDINT_H" - else ifeq ($(CONFIG),wasi) ifeq ($(WASI_SDK),) CXX = clang++ @@ -301,25 +304,13 @@ LINK_ABC := 1 DISABLE_ABC_THREADS := 1 endif -else ifeq ($(CONFIG),mxe) -PKG_CONFIG = /usr/local/src/mxe/usr/bin/i686-w64-mingw32.static-pkg-config -CXX = /usr/local/src/mxe/usr/bin/i686-w64-mingw32.static-g++ -CXXFLAGS += -std=$(CXXSTD) $(OPT_LEVEL) -D_POSIX_SOURCE -DYOSYS_MXE_HACKS -Wno-attributes -CXXFLAGS := $(filter-out -fPIC,$(CXXFLAGS)) -LINKFLAGS := $(filter-out -rdynamic,$(LINKFLAGS)) -s -LIBS := $(filter-out -lrt,$(LIBS)) -ABCMKARGS += ARCHFLAGS="-DWIN32_NO_DLL -DHAVE_STRUCT_TIMESPEC -fpermissive -w" -# TODO: Try to solve pthread linking issue in more appropriate way -ABCMKARGS += LIBS="lib/x86/pthreadVC2.lib -s" LINKFLAGS="-Wl,--allow-multiple-definition" ABC_USE_NO_READLINE=1 CC="/usr/local/src/mxe/usr/bin/i686-w64-mingw32.static-gcc" -EXE = .exe - else ifeq ($(CONFIG),msys2-32) CXX = i686-w64-mingw32-g++ CXXFLAGS += -std=$(CXXSTD) $(OPT_LEVEL) -D_POSIX_SOURCE -DYOSYS_WIN32_UNIX_DIR CXXFLAGS := $(filter-out -fPIC,$(CXXFLAGS)) LINKFLAGS := $(filter-out -rdynamic,$(LINKFLAGS)) -s LIBS := $(filter-out -lrt,$(LIBS)) -ABCMKARGS += ARCHFLAGS="-DABC_USE_STDINT_H -DWIN32_NO_DLL -DHAVE_STRUCT_TIMESPEC -fpermissive -w" +ABCMKARGS += ARCHFLAGS="-DABC_USE_STDINT_H -DWIN32_NO_DLL -DWIN32 -DHAVE_STRUCT_TIMESPEC -fpermissive -w" ABCMKARGS += LIBS="-lpthread -lshlwapi -s" ABC_USE_NO_READLINE=0 CC="i686-w64-mingw32-gcc" CXX="$(CXX)" EXE = .exe @@ -329,7 +320,7 @@ CXXFLAGS += -std=$(CXXSTD) $(OPT_LEVEL) -D_POSIX_SOURCE -DYOSYS_WIN32_UNIX_DIR CXXFLAGS := $(filter-out -fPIC,$(CXXFLAGS)) LINKFLAGS := $(filter-out -rdynamic,$(LINKFLAGS)) -s LIBS := $(filter-out -lrt,$(LIBS)) -ABCMKARGS += ARCHFLAGS="-DABC_USE_STDINT_H -DWIN32_NO_DLL -DHAVE_STRUCT_TIMESPEC -fpermissive -w" +ABCMKARGS += ARCHFLAGS="-DABC_USE_STDINT_H -DWIN32_NO_DLL -DWIN32 -DHAVE_STRUCT_TIMESPEC -fpermissive -w" ABCMKARGS += LIBS="-lpthread -lshlwapi -s" ABC_USE_NO_READLINE=0 CC="x86_64-w64-mingw32-gcc" CXX="$(CXX)" EXE = .exe @@ -339,7 +330,7 @@ ABCMKARGS += ARCHFLAGS="-DABC_USE_STDINT_H $(ABC_ARCHFLAGS)" LTOFLAGS = else -$(error Invalid CONFIG setting '$(CONFIG)'. Valid values: clang, gcc, mxe, msys2-32, msys2-64, none) +$(error Invalid CONFIG setting '$(CONFIG)'. Valid values: clang, gcc, msys2-32, msys2-64, none) endif @@ -353,8 +344,14 @@ TARGETS += libyosys.so endif ifeq ($(ENABLE_PYOSYS),1) +# python-config --ldflags includes -l and -L, but LINKFLAGS is only -L +LINKFLAGS += $(filter-out -l%,$(shell $(PYTHON_CONFIG) --ldflags)) +LIBS += $(shell $(PYTHON_CONFIG) --libs) +EXE_LIBS += $(filter-out $(LIBS),$(shell $(PYTHON_CONFIG_FOR_EXE) --libs)) +CXXFLAGS += $(shell $(PYTHON_CONFIG) --includes) -DWITH_PYTHON + # Detect name of boost_python library. Some distros use boost_python-py, other boost_python, some only use the major version number, some a concatenation of major and minor version numbers -CHECK_BOOST_PYTHON = (echo "int main(int argc, char ** argv) {return 0;}" | $(CXX) -xc -o /dev/null $(shell $(PYTHON_CONFIG) --ldflags) -l$(1) - > /dev/null 2>&1 && echo "-l$(1)") +CHECK_BOOST_PYTHON = (echo "int main(int argc, char ** argv) {return 0;}" | $(CXX) -xc -o /dev/null $(LINKFLAGS) $(EXE_LIBS) $(LIBS) -l$(1) - > /dev/null 2>&1 && echo "-l$(1)") BOOST_PYTHON_LIB ?= $(shell \ $(call CHECK_BOOST_PYTHON,boost_python-py$(subst .,,$(PYTHON_VERSION))) || \ $(call CHECK_BOOST_PYTHON,boost_python-py$(PYTHON_MAJOR_VERSION)) || \ @@ -366,15 +363,11 @@ ifeq ($(BOOST_PYTHON_LIB),) $(error BOOST_PYTHON_LIB could not be detected. Please define manually) endif -LIBS += $(shell $(PYTHON_CONFIG) --libs) $(BOOST_PYTHON_LIB) -lboost_system -lboost_filesystem -# python-config --ldflags includes LIBS for some reason -LINKFLAGS += $(filter-out -l%,$(shell $(PYTHON_CONFIG) --ldflags)) -CXXFLAGS += $(shell $(PYTHON_CONFIG) --includes) -DWITH_PYTHON - +LIBS += $(BOOST_PYTHON_LIB) -lboost_system -lboost_filesystem PY_WRAPPER_FILE = kernel/python_wrappers OBJS += $(PY_WRAPPER_FILE).o PY_GEN_SCRIPT= py_wrap_generator -PY_WRAP_INCLUDES := $(shell python$(PYTHON_VERSION) -c "from misc import $(PY_GEN_SCRIPT); $(PY_GEN_SCRIPT).print_includes()") +PY_WRAP_INCLUDES := $(shell $(PYTHON_EXECUTABLE) -c "from misc import $(PY_GEN_SCRIPT); $(PY_GEN_SCRIPT).print_includes()") endif # ENABLE_PYOSYS ifeq ($(ENABLE_READLINE),1) @@ -391,22 +384,22 @@ ifeq ($(LINK_TERMCAP),1) LIBS += -ltermcap ABCMKARGS += "ABC_READLINE_LIBRARIES=-lreadline -ltermcap" endif -ifeq ($(CONFIG),mxe) -LIBS += -ltermcap -endif else ifeq ($(ENABLE_EDITLINE),1) CXXFLAGS += -DYOSYS_ENABLE_EDITLINE -LIBS += -ledit -ltinfo -lbsd -else -ABCMKARGS += "ABC_USE_NO_READLINE=1" +LIBS += -ledit endif +ABCMKARGS += "ABC_USE_NO_READLINE=1" endif ifeq ($(DISABLE_ABC_THREADS),1) ABCMKARGS += "ABC_USE_NO_PTHREADS=1" endif +ifeq ($(LINK_ABC),1) +ABCMKARGS += "ABC_USE_PIC=1" +endif + ifeq ($(DISABLE_SPAWN),1) CXXFLAGS += -DYOSYS_DISABLE_SPAWN endif @@ -443,12 +436,10 @@ TCL_INCLUDE ?= /usr/include/$(TCL_VERSION) TCL_LIBS ?= -l$(TCL_VERSION) endif -ifeq ($(CONFIG),mxe) -CXXFLAGS += -DYOSYS_ENABLE_TCL -LIBS += -ltcl86 -lwsock32 -lws2_32 -lnetapi32 -lz -luserenv -else CXXFLAGS += $(shell PKG_CONFIG_PATH=$(PKG_CONFIG_PATH) $(PKG_CONFIG) --silence-errors --cflags tcl || echo -I$(TCL_INCLUDE)) -DYOSYS_ENABLE_TCL LIBS += $(shell PKG_CONFIG_PATH=$(PKG_CONFIG_PATH) $(PKG_CONFIG) --silence-errors --libs tcl || echo $(TCL_LIBS)) +ifneq (,$(findstring TCL_WITH_EXTERNAL_TOMMATH,$(CXXFLAGS))) +LIBS += $(shell PKG_CONFIG_PATH=$(PKG_CONFIG_PATH) $(PKG_CONFIG) --silence-errors --libs libtommath || echo) endif endif @@ -464,6 +455,7 @@ endif ifeq ($(ENABLE_DEBUG),1) CXXFLAGS := -Og -DDEBUG $(filter-out $(OPT_LEVEL),$(CXXFLAGS)) +STRIP := endif ifeq ($(ENABLE_ABC),1) @@ -607,7 +599,9 @@ $(eval $(call add_include_file,kernel/fmt.h)) ifeq ($(ENABLE_ZLIB),1) $(eval $(call add_include_file,kernel/fstdata.h)) endif +$(eval $(call add_include_file,kernel/gzip.h)) $(eval $(call add_include_file,kernel/hashlib.h)) +$(eval $(call add_include_file,kernel/io.h)) $(eval $(call add_include_file,kernel/json.h)) $(eval $(call add_include_file,kernel/log.h)) $(eval $(call add_include_file,kernel/macc.h)) @@ -633,13 +627,14 @@ endif $(eval $(call add_include_file,libs/sha1/sha1.h)) $(eval $(call add_include_file,libs/json11/json11.hpp)) $(eval $(call add_include_file,passes/fsm/fsmdata.h)) +$(eval $(call add_include_file,passes/techmap/libparse.h)) $(eval $(call add_include_file,frontends/ast/ast.h)) $(eval $(call add_include_file,frontends/ast/ast_binding.h)) $(eval $(call add_include_file,frontends/blif/blifparse.h)) $(eval $(call add_include_file,backends/rtlil/rtlil_backend.h)) -OBJS += kernel/driver.o kernel/register.o kernel/rtlil.o kernel/log.o kernel/calc.o kernel/yosys.o -OBJS += kernel/binding.o +OBJS += kernel/driver.o kernel/register.o kernel/rtlil.o kernel/log.o kernel/calc.o kernel/yosys.o kernel/io.o kernel/gzip.o +OBJS += kernel/binding.o kernel/tclapi.o OBJS += kernel/cellaigs.o kernel/celledges.o kernel/cost.o kernel/satgen.o kernel/scopeinfo.o kernel/qcsat.o kernel/mem.o kernel/ffmerge.o kernel/ff.o kernel/yw.o kernel/json.o kernel/fmt.o kernel/sexpr.o OBJS += kernel/drivertools.o kernel/functional.o ifeq ($(ENABLE_ZLIB),1) @@ -680,6 +675,9 @@ OBJS += libs/fst/fastlz.o OBJS += libs/fst/lz4.o endif +techlibs/%_pm.h: passes/pmgen/pmgen.py techlibs/%.pmg + $(P) mkdir -p $(dir $@) && $(PYTHON_EXECUTABLE) $< -o $@ -p $(notdir $*) $(filter-out $<,$^) + ifneq ($(SMALL),1) OBJS += libs/subcircuit/subcircuit.o @@ -737,12 +735,18 @@ compile-only: $(OBJS) $(GENFILES) $(EXTRA_TARGETS) @echo " Compile successful." @echo "" +.PHONY: share +share: $(EXTRA_TARGETS) + @echo "" + @echo " Share directory created." + @echo "" + $(PROGRAM_PREFIX)yosys$(EXE): $(OBJS) - $(P) $(CXX) -o $(PROGRAM_PREFIX)yosys$(EXE) $(EXE_LINKFLAGS) $(LINKFLAGS) $(OBJS) $(LIBS) $(LIBS_VERIFIC) + $(P) $(CXX) -o $(PROGRAM_PREFIX)yosys$(EXE) $(EXE_LINKFLAGS) $(LINKFLAGS) $(OBJS) $(EXE_LIBS) $(LIBS) $(LIBS_VERIFIC) libyosys.so: $(filter-out kernel/driver.o,$(OBJS)) ifeq ($(OS), Darwin) - $(P) $(CXX) -o libyosys.so -shared -Wl,-install_name,$(LIBDIR)/libyosys.so $(LINKFLAGS) $^ $(LIBS) $(LIBS_VERIFIC) + $(P) $(CXX) -o libyosys.so -shared -undefined dynamic_lookup -Wl,-install_name,$(LIBDIR)/libyosys.so $(LINKFLAGS) $^ $(LIBS) $(LIBS_VERIFIC) else $(P) $(CXX) -o libyosys.so -shared -Wl,-soname,$(LIBDIR)/libyosys.so $(LINKFLAGS) $^ $(LIBS) $(LIBS_VERIFIC) endif @@ -758,7 +762,7 @@ endif ifeq ($(ENABLE_PYOSYS),1) $(PY_WRAPPER_FILE).cc: misc/$(PY_GEN_SCRIPT).py $(PY_WRAP_INCLUDES) $(Q) mkdir -p $(dir $@) - $(P) python$(PYTHON_VERSION) -c "from misc import $(PY_GEN_SCRIPT); $(PY_GEN_SCRIPT).gen_wrappers(\"$(PY_WRAPPER_FILE).cc\")" + $(P) $(PYTHON_EXECUTABLE) -c "from misc import $(PY_GEN_SCRIPT); $(PY_GEN_SCRIPT).gen_wrappers(\"$(PY_WRAPPER_FILE).cc\")" endif %.o: %.cpp @@ -789,7 +793,7 @@ $(PROGRAM_PREFIX)yosys-config: misc/yosys-config.in $(YOSYS_SRC)/Makefile .PHONY: check-git-abc check-git-abc: - @if [ ! -d "$(YOSYS_SRC)/abc" ]; then \ + @if [ ! -d "$(YOSYS_SRC)/abc" ] && git -C "$(YOSYS_SRC)" status >/dev/null 2>&1; then \ echo "Error: The 'abc' directory does not exist."; \ echo "Initialize the submodule: Run 'git submodule update --init' to set up 'abc' as a submodule."; \ exit 1; \ @@ -798,6 +802,15 @@ check-git-abc: elif [ -f "$(YOSYS_SRC)/abc/.gitcommit" ] && ! grep -q '\$$Format:%[hH]\$$' "$(YOSYS_SRC)/abc/.gitcommit"; then \ echo "'abc' comes from a tarball. Continuing."; \ exit 0; \ + elif git -C "$(YOSYS_SRC)" submodule status abc 2>/dev/null | grep -q '^+'; then \ + echo "'abc' submodule does not match expected commit."; \ + echo "Run 'git submodule update' to check out the correct version."; \ + echo "Note: If testing a different version of abc, call 'git commit abc' in the Yosys source directory to update the expected commit."; \ + exit 1; \ + elif git -C "$(YOSYS_SRC)" submodule status abc 2>/dev/null | grep -q '^U'; then \ + echo "'abc' submodule has merge conflicts."; \ + echo "Please resolve merge conflicts before continuing."; \ + exit 1; \ elif [ -f "$(YOSYS_SRC)/abc/.gitcommit" ] && grep -q '\$$Format:%[hH]\$$' "$(YOSYS_SRC)/abc/.gitcommit"; then \ echo "Error: 'abc' is not configured as a git submodule."; \ echo "To resolve this:"; \ @@ -806,6 +819,12 @@ check-git-abc: echo "3. Initialize the submodule: Run 'git submodule update --init' to set up 'abc' as a submodule."; \ echo "4. Reapply your changes: Move your saved changes back to the 'abc' directory, if necessary."; \ exit 1; \ + elif ! git -C "$(YOSYS_SRC)" status >/dev/null 2>&1; then \ + echo "$(realpath $(YOSYS_SRC)) is not configured as a git repository, and 'abc' folder is missing."; \ + echo "If you already have ABC, set 'ABCEXTERNAL' make variable to point to ABC executable."; \ + echo "Otherwise, download release archive 'yosys.tar.gz' from https://github.com/YosysHQ/yosys/releases."; \ + echo " ('Source code' archive does not contain submodules.)"; \ + exit 1; \ else \ echo "Initialize the submodule: Run 'git submodule update --init' to set up 'abc' as a submodule."; \ exit 1; \ @@ -833,71 +852,104 @@ else ABCOPT="" endif -# When YOSYS_NOVERIFIC is set as a make variable, also export it to the -# enviornment, so that `YOSYS_NOVERIFIC=1 make test` _and_ -# `make test YOSYS_NOVERIFIC=1` will run with verific disabled. -ifeq ($(YOSYS_NOVERIFIC),1) -export YOSYS_NOVERIFIC +# Tests that generate .mk with tests/gen-tests-makefile.sh +MK_TEST_DIRS = +MK_TEST_DIRS += tests/arch/anlogic +MK_TEST_DIRS += tests/arch/ecp5 +MK_TEST_DIRS += tests/arch/efinix +MK_TEST_DIRS += tests/arch/gatemate +MK_TEST_DIRS += tests/arch/gowin +MK_TEST_DIRS += tests/arch/ice40 +MK_TEST_DIRS += tests/arch/intel_alm +MK_TEST_DIRS += tests/arch/machxo2 +MK_TEST_DIRS += tests/arch/microchip +MK_TEST_DIRS += tests/arch/nanoxplore +MK_TEST_DIRS += tests/arch/nexus +MK_TEST_DIRS += tests/arch/quicklogic/pp3 +MK_TEST_DIRS += tests/arch/quicklogic/qlf_k6n10f +MK_TEST_DIRS += tests/arch/xilinx +MK_TEST_DIRS += tests/bugpoint +MK_TEST_DIRS += tests/opt +MK_TEST_DIRS += tests/sat +MK_TEST_DIRS += tests/sim +MK_TEST_DIRS += tests/svtypes +MK_TEST_DIRS += tests/techmap +MK_TEST_DIRS += tests/various +ifeq ($(ENABLE_VERIFIC),1) +ifneq ($(YOSYS_NOVERIFIC),1) +MK_TEST_DIRS += tests/verific +endif +endif +MK_TEST_DIRS += tests/verilog + +# Tests that don't generate .mk +SH_TEST_DIRS = +SH_TEST_DIRS += tests/simple +SH_TEST_DIRS += tests/simple_abc9 +SH_TEST_DIRS += tests/hana +SH_TEST_DIRS += tests/asicworld +# SH_TEST_DIRS += tests/realmath +SH_TEST_DIRS += tests/share +SH_TEST_DIRS += tests/opt_share +SH_TEST_DIRS += tests/fsm +SH_TEST_DIRS += tests/memlib +SH_TEST_DIRS += tests/bram +SH_TEST_DIRS += tests/svinterfaces +SH_TEST_DIRS += tests/xprop +SH_TEST_DIRS += tests/select +SH_TEST_DIRS += tests/peepopt +SH_TEST_DIRS += tests/proc +SH_TEST_DIRS += tests/blif +SH_TEST_DIRS += tests/arch +SH_TEST_DIRS += tests/rpc +SH_TEST_DIRS += tests/memfile +SH_TEST_DIRS += tests/fmt +SH_TEST_DIRS += tests/cxxrtl +SH_TEST_DIRS += tests/liberty +ifeq ($(ENABLE_FUNCTIONAL_TESTS),1) +SH_TEST_DIRS += tests/functional endif -test: $(TARGETS) $(EXTRA_TARGETS) -ifeq ($(ENABLE_VERIFIC),1) -ifeq ($(YOSYS_NOVERIFIC),1) - @echo - @echo "Running tests without verific support due to YOSYS_NOVERIFIC=1" - @echo -else - +cd tests/verific && bash run-test.sh $(SEEDOPT) -endif -endif - +cd tests/simple && bash run-test.sh $(SEEDOPT) - +cd tests/simple_abc9 && bash run-test.sh $(SEEDOPT) - +cd tests/hana && bash run-test.sh $(SEEDOPT) - +cd tests/asicworld && bash run-test.sh $(SEEDOPT) - # +cd tests/realmath && bash run-test.sh $(SEEDOPT) - +cd tests/share && bash run-test.sh $(SEEDOPT) - +cd tests/opt_share && bash run-test.sh $(SEEDOPT) - +cd tests/fsm && bash run-test.sh $(SEEDOPT) - +cd tests/techmap && bash run-test.sh - +cd tests/memories && bash run-test.sh $(ABCOPT) $(SEEDOPT) - +cd tests/memlib && bash run-test.sh $(SEEDOPT) - +cd tests/bram && bash run-test.sh $(SEEDOPT) - +cd tests/various && bash run-test.sh - +cd tests/select && bash run-test.sh - +cd tests/sat && bash run-test.sh - +cd tests/sim && bash run-test.sh - +cd tests/svinterfaces && bash run-test.sh $(SEEDOPT) - +cd tests/svtypes && bash run-test.sh $(SEEDOPT) - +cd tests/proc && bash run-test.sh - +cd tests/blif && bash run-test.sh - +cd tests/opt && bash run-test.sh - +cd tests/aiger && bash run-test.sh $(ABCOPT) - +cd tests/arch && bash run-test.sh - +cd tests/arch/ice40 && bash run-test.sh $(SEEDOPT) - +cd tests/arch/xilinx && bash run-test.sh $(SEEDOPT) - +cd tests/arch/ecp5 && bash run-test.sh $(SEEDOPT) - +cd tests/arch/machxo2 && bash run-test.sh $(SEEDOPT) - +cd tests/arch/efinix && bash run-test.sh $(SEEDOPT) - +cd tests/arch/anlogic && bash run-test.sh $(SEEDOPT) - +cd tests/arch/gowin && bash run-test.sh $(SEEDOPT) - +cd tests/arch/intel_alm && bash run-test.sh $(SEEDOPT) - +cd tests/arch/nanoxplore && bash run-test.sh $(SEEDOPT) - +cd tests/arch/nexus && bash run-test.sh $(SEEDOPT) - +cd tests/arch/quicklogic/pp3 && bash run-test.sh $(SEEDOPT) - +cd tests/arch/quicklogic/qlf_k6n10f && bash run-test.sh $(SEEDOPT) - +cd tests/arch/gatemate && bash run-test.sh $(SEEDOPT) - +cd tests/arch/microchip && bash run-test.sh $(SEEDOPT) - +cd tests/rpc && bash run-test.sh - +cd tests/memfile && bash run-test.sh - +cd tests/verilog && bash run-test.sh - +cd tests/xprop && bash run-test.sh $(SEEDOPT) - +cd tests/fmt && bash run-test.sh - +cd tests/cxxrtl && bash run-test.sh -ifeq ($(ENABLE_FUNCTIONAL_TESTS),1) - +cd tests/functional && bash run-test.sh -endif +# Tests that don't generate .mk and need special args +SH_ABC_TEST_DIRS = +SH_ABC_TEST_DIRS += tests/memories +SH_ABC_TEST_DIRS += tests/aiger +SH_ABC_TEST_DIRS += tests/alumacc + +# seed-tests/ is a dummy string, not a directory +.PHONY: seed-tests +seed-tests: $(SH_TEST_DIRS:%=seed-tests/%) +.PHONY: seed-tests/% +seed-tests/%: %/run-test.sh $(TARGETS) $(EXTRA_TARGETS) + +cd $* && bash run-test.sh $(SEEDOPT) + +@echo "...passed tests in $*" + +# abcopt-tests/ is a dummy string, not a directory +.PHONY: abcopt-tests +abcopt-tests: $(SH_ABC_TEST_DIRS:%=abcopt-tests/%) +abcopt-tests/%: %/run-test.sh $(TARGETS) $(EXTRA_TARGETS) + +cd $* && bash run-test.sh $(ABCOPT) $(SEEDOPT) + +@echo "...passed tests in $*" + +# makefile-tests/ is a dummy string, not a directory +.PHONY: makefile-tests +makefile-tests: $(MK_TEST_DIRS:%=makefile-tests/%) +# this target actually emits .mk files +%.mk: + +cd $(dir $*) && bash run-test.sh +# this one spawns submake on each +makefile-tests/%: %/run-test.mk $(TARGETS) $(EXTRA_TARGETS) + $(MAKE) -C $* -f run-test.mk + +@echo "...passed tests in $*" + +test: makefile-tests abcopt-tests seed-tests @echo "" @echo " Passed \"make test\"." +ifeq ($(ENABLE_VERIFIC),1) +ifeq ($(YOSYS_NOVERIFIC),1) + @echo " Ran tests without verific support due to YOSYS_NOVERIFIC=1." +endif +endif @echo "" VALGRIND ?= valgrind --error-exitcode=1 --leak-check=full --show-reachable=yes --errors-for-leak-kinds=all @@ -924,33 +976,43 @@ ystests: $(TARGETS) $(EXTRA_TARGETS) # Unit test unit-test: libyosys.so - @$(MAKE) -C $(UNITESTPATH) CXX="$(CXX)" CPPFLAGS="$(CPPFLAGS)" \ - CXXFLAGS="$(CXXFLAGS)" LIBS="$(LIBS)" ROOTPATH="$(CURDIR)" + @$(MAKE) -C $(UNITESTPATH) CXX="$(CXX)" CC="$(CC)" CPPFLAGS="$(CPPFLAGS)" \ + CXXFLAGS="$(CXXFLAGS)" LINKFLAGS="$(LINKFLAGS)" LIBS="$(LIBS)" ROOTPATH="$(CURDIR)" clean-unit-test: @$(MAKE) -C $(UNITESTPATH) clean +install-dev: $(PROGRAM_PREFIX)yosys-config share + $(INSTALL_SUDO) mkdir -p $(DESTDIR)$(BINDIR) + $(INSTALL_SUDO) cp $(PROGRAM_PREFIX)yosys-config $(DESTDIR)$(BINDIR) + $(INSTALL_SUDO) mkdir -p $(DESTDIR)$(DATDIR) + $(INSTALL_SUDO) cp -r share/. $(DESTDIR)$(DATDIR)/. + install: $(TARGETS) $(EXTRA_TARGETS) $(INSTALL_SUDO) mkdir -p $(DESTDIR)$(BINDIR) $(INSTALL_SUDO) cp $(filter-out libyosys.so,$(TARGETS)) $(DESTDIR)$(BINDIR) ifneq ($(filter $(PROGRAM_PREFIX)yosys,$(TARGETS)),) - $(INSTALL_SUDO) $(STRIP) -S $(DESTDIR)$(BINDIR)/$(PROGRAM_PREFIX)yosys + if [ -n "$(STRIP)" ]; then $(INSTALL_SUDO) $(STRIP) -S $(DESTDIR)$(BINDIR)/$(PROGRAM_PREFIX)yosys; fi endif ifneq ($(filter $(PROGRAM_PREFIX)yosys-abc,$(TARGETS)),) - $(INSTALL_SUDO) $(STRIP) $(DESTDIR)$(BINDIR)/$(PROGRAM_PREFIX)yosys-abc + if [ -n "$(STRIP)" ]; then $(INSTALL_SUDO) $(STRIP) $(DESTDIR)$(BINDIR)/$(PROGRAM_PREFIX)yosys-abc; fi endif ifneq ($(filter $(PROGRAM_PREFIX)yosys-filterlib,$(TARGETS)),) - $(INSTALL_SUDO) $(STRIP) $(DESTDIR)$(BINDIR)/$(PROGRAM_PREFIX)yosys-filterlib + if [ -n "$(STRIP)" ]; then $(INSTALL_SUDO) $(STRIP) $(DESTDIR)$(BINDIR)/$(PROGRAM_PREFIX)yosys-filterlib; fi endif $(INSTALL_SUDO) mkdir -p $(DESTDIR)$(DATDIR) $(INSTALL_SUDO) cp -r share/. $(DESTDIR)$(DATDIR)/. ifeq ($(ENABLE_LIBYOSYS),1) $(INSTALL_SUDO) mkdir -p $(DESTDIR)$(LIBDIR) $(INSTALL_SUDO) cp libyosys.so $(DESTDIR)$(LIBDIR)/ - $(INSTALL_SUDO) $(STRIP) -S $(DESTDIR)$(LIBDIR)/libyosys.so + if [ -n "$(STRIP)" ]; then $(INSTALL_SUDO) $(STRIP) -S $(DESTDIR)$(LIBDIR)/libyosys.so; fi ifeq ($(ENABLE_PYOSYS),1) $(INSTALL_SUDO) mkdir -p $(DESTDIR)$(PYTHON_DESTDIR)/$(subst -,_,$(PROGRAM_PREFIX))pyosys $(INSTALL_SUDO) cp libyosys.so $(DESTDIR)$(PYTHON_DESTDIR)/$(subst -,_,$(PROGRAM_PREFIX))pyosys/libyosys.so + $(INSTALL_SUDO) cp -r share $(DESTDIR)$(PYTHON_DESTDIR)/$(subst -,_,$(PROGRAM_PREFIX))pyosys +ifeq ($(ENABLE_ABC),1) + $(INSTALL_SUDO) cp yosys-abc $(DESTDIR)$(PYTHON_DESTDIR)/$(subst -,_,$(PROGRAM_PREFIX))pyosys/yosys-abc +endif $(INSTALL_SUDO) cp misc/__init__.py $(DESTDIR)$(PYTHON_DESTDIR)/$(subst -,_,$(PROGRAM_PREFIX))pyosys/ endif endif @@ -975,27 +1037,46 @@ endif # also others, but so long as it doesn't fail this is enough to know we tried docs/source/cmd/abc.rst: $(TARGETS) $(EXTRA_TARGETS) - mkdir -p docs/source/cmd - ./$(PROGRAM_PREFIX)yosys -p 'help -write-rst-command-reference-manual' + $(Q) mkdir -p docs/source/cmd + $(Q) mkdir -p temp/docs/source/cmd + $(Q) cd temp && ./../$(PROGRAM_PREFIX)yosys -p 'help -write-rst-command-reference-manual' + $(Q) $(RSYNC_CP) temp/docs/source/cmd docs/source + $(Q) rm -rf temp +docs/source/cell/word_add.rst: $(TARGETS) $(EXTRA_TARGETS) + $(Q) mkdir -p docs/source/cell + $(Q) mkdir -p temp/docs/source/cell + $(Q) cd temp && ./../$(PROGRAM_PREFIX)yosys -p 'help -write-rst-cells-manual' + $(Q) $(RSYNC_CP) temp/docs/source/cell docs/source + $(Q) rm -rf temp -PHONY: docs/gen_examples docs/gen_images docs/guidelines docs/usage docs/reqs -docs/gen_examples: - $(Q) $(MAKE) -C docs examples +docs/source/generated/cells.json: docs/source/generated $(TARGETS) $(EXTRA_TARGETS) + $(Q) ./$(PROGRAM_PREFIX)yosys -p 'help -dump-cells-json $@' -docs/gen_images: - $(Q) $(MAKE) -C docs images +docs/source/generated/%.cc: backends/%.cc + $(Q) mkdir -p $(@D) + $(Q) cp $< $@ -DOCS_GUIDELINE_FILES := GettingStarted CodingStyle -docs/guidelines docs/source/generated: +# diff returns exit code 1 if the files are different, but it's not an error +docs/source/generated/functional/rosette.diff: backends/functional/smtlib.cc backends/functional/smtlib_rosette.cc + $(Q) mkdir -p $(@D) + $(Q) diff -U 20 $^ > $@ || exit 0 + +PHONY: docs/gen/functional_ir +docs/gen/functional_ir: docs/source/generated/functional/smtlib.cc docs/source/generated/functional/rosette.diff + +PHONY: docs/gen docs/usage docs/reqs +docs/gen: $(TARGETS) + $(Q) $(MAKE) -C docs gen + +docs/source/generated: $(Q) mkdir -p docs/source/generated - $(Q) cp -f $(addprefix guidelines/,$(DOCS_GUIDELINE_FILES)) docs/source/generated # some commands return an error and print the usage text to stderr define DOC_USAGE_STDERR -docs/source/generated/$(1): $(TARGETS) docs/source/generated +docs/source/generated/$(1): $(TARGETS) docs/source/generated FORCE -$(Q) ./$(PROGRAM_PREFIX)$(1) --help 2> $$@ endef -DOCS_USAGE_STDERR := yosys-config yosys-filterlib +DOCS_USAGE_STDERR := yosys-filterlib # The in-tree ABC (yosys-abc) is only built when ABCEXTERNAL is not set. ifeq ($(ABCEXTERNAL),) @@ -1007,9 +1088,9 @@ $(foreach usage,$(DOCS_USAGE_STDERR),$(eval $(call DOC_USAGE_STDERR,$(usage)))) # others print to stdout define DOC_USAGE_STDOUT docs/source/generated/$(1): $(TARGETS) docs/source/generated - $(Q) ./$(PROGRAM_PREFIX)$(1) --help > $$@ + $(Q) ./$(PROGRAM_PREFIX)$(1) --help > $$@ || rm $$@ endef -DOCS_USAGE_STDOUT := yosys yosys-smtbmc yosys-witness +DOCS_USAGE_STDOUT := yosys yosys-smtbmc yosys-witness yosys-config $(foreach usage,$(DOCS_USAGE_STDOUT),$(eval $(call DOC_USAGE_STDOUT,$(usage)))) docs/usage: $(addprefix docs/source/generated/,$(DOCS_USAGE_STDOUT) $(DOCS_USAGE_STDERR)) @@ -1018,7 +1099,7 @@ docs/reqs: $(Q) $(MAKE) -C docs reqs .PHONY: docs/prep -docs/prep: docs/source/cmd/abc.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage +docs/prep: docs/source/cmd/abc.rst docs/source/generated/cells.json docs/gen docs/usage docs/gen/functional_ir DOC_TARGET ?= html docs: docs/prep @@ -1029,6 +1110,7 @@ clean: rm -rf kernel/*.pyh rm -f $(OBJS) $(GENFILES) $(TARGETS) $(EXTRA_TARGETS) $(EXTRA_OBJS) $(PY_WRAP_INCLUDES) $(PY_WRAPPER_FILE).cc rm -f kernel/version_*.o kernel/version_*.cc + rm -f kernel/python_wrappers.o rm -f libs/*/*.d frontends/*/*.d passes/*/*.d backends/*/*.d kernel/*.d techlibs/*/*.d rm -rf tests/asicworld/*.out tests/asicworld/*.log rm -rf tests/hana/*.out tests/hana/*.log @@ -1039,9 +1121,11 @@ clean: rm -rf vloghtb/Makefile vloghtb/refdat vloghtb/rtl vloghtb/scripts vloghtb/spec vloghtb/check_yosys vloghtb/vloghammer_tb.tar.bz2 vloghtb/temp vloghtb/log_test_* rm -f tests/svinterfaces/*.log_stdout tests/svinterfaces/*.log_stderr tests/svinterfaces/dut_result.txt tests/svinterfaces/reference_result.txt tests/svinterfaces/a.out tests/svinterfaces/*_syn.v tests/svinterfaces/*.diff rm -f tests/tools/cmp_tbdata + rm -f $(addsuffix /run-test.mk,$(MK_TEST_DIRS)) -$(MAKE) -C docs clean - -$(MAKE) -C docs/images clean rm -rf docs/source/cmd docs/util/__pycache__ + rm -f *.whl + rm -f libyosys.so clean-abc: $(MAKE) -C abc DEP= clean @@ -1078,25 +1162,13 @@ vcxsrc: $(GENFILES) $(EXTRA_TARGETS) rm -rf yosys-win32-vcxsrc-$(YOSYS_VER){,.zip} set -e; for f in `ls $(filter %.cc %.cpp,$(GENFILES)) $(addsuffix .cc,$(basename $(OBJS))) $(addsuffix .cpp,$(basename $(OBJS))) 2> /dev/null`; do \ echo "Analyse: $$f" >&2; cpp -std=c++17 -MM -I. -D_YOSYS_ $$f; done | sed 's,.*:,,; s,//*,/,g; s,/[^/]*/\.\./,/,g; y, \\,\n\n,;' | grep '^[^/]' | sort -u | grep -v kernel/version_ > srcfiles.txt + echo "libs/fst/fst_win_unistd.h" >> srcfiles.txt bash misc/create_vcxsrc.sh yosys-win32-vcxsrc $(YOSYS_VER) $(GIT_REV) echo "namespace Yosys { extern const char *yosys_version_str; const char *yosys_version_str=\"Yosys (Version Information Unavailable)\"; }" > kernel/version.cc zip yosys-win32-vcxsrc-$(YOSYS_VER)/genfiles.zip $(GENFILES) kernel/version.cc zip -r yosys-win32-vcxsrc-$(YOSYS_VER).zip yosys-win32-vcxsrc-$(YOSYS_VER)/ rm -f srcfiles.txt kernel/version.cc -ifeq ($(CONFIG),mxe) -mxebin: $(TARGETS) $(EXTRA_TARGETS) - rm -rf yosys-win32-mxebin-$(YOSYS_VER){,.zip} - mkdir -p yosys-win32-mxebin-$(YOSYS_VER) - cp -r $(PROGRAM_PREFIX)yosys.exe share/ yosys-win32-mxebin-$(YOSYS_VER)/ -ifeq ($(ENABLE_ABC),1) - cp -r $(PROGRAM_PREFIX)yosys-abc.exe abc/lib/x86/pthreadVC2.dll yosys-win32-mxebin-$(YOSYS_VER)/ -endif - echo -en 'This is Yosys $(YOSYS_VER) for Win32.\r\n' > yosys-win32-mxebin-$(YOSYS_VER)/readme.txt - echo -en 'Documentation at https://yosyshq.net/yosys/.\r\n' >> yosys-win32-mxebin-$(YOSYS_VER)/readme.txt - zip -r yosys-win32-mxebin-$(YOSYS_VER).zip yosys-win32-mxebin-$(YOSYS_VER)/ -endif - config-clean: clean rm -f Makefile.conf @@ -1112,9 +1184,6 @@ config-gcc-static: clean echo 'ENABLE_READLINE := 0' >> Makefile.conf echo 'ENABLE_TCL := 0' >> Makefile.conf -config-afl-gcc: clean - echo 'CONFIG := afl-gcc' > Makefile.conf - config-wasi: clean echo 'CONFIG := wasi' > Makefile.conf echo 'ENABLE_TCL := 0' >> Makefile.conf @@ -1123,10 +1192,6 @@ config-wasi: clean echo 'ENABLE_READLINE := 0' >> Makefile.conf echo 'ENABLE_ZLIB := 0' >> Makefile.conf -config-mxe: clean - echo 'CONFIG := mxe' > Makefile.conf - echo 'ENABLE_PLUGINS := 0' >> Makefile.conf - config-msys2-32: clean echo 'CONFIG := msys2-32' > Makefile.conf echo "PREFIX := $(MINGW_PREFIX)" >> Makefile.conf @@ -1135,9 +1200,6 @@ config-msys2-64: clean echo 'CONFIG := msys2-64' > Makefile.conf echo "PREFIX := $(MINGW_PREFIX)" >> Makefile.conf -config-cygwin: clean - echo 'CONFIG := cygwin' > Makefile.conf - config-gcov: clean echo 'CONFIG := gcc' > Makefile.conf echo 'ENABLE_GCOV := 1' >> Makefile.conf @@ -1166,5 +1228,7 @@ echo-cxx: -include kernel/*.d -include techlibs/*/*.d -.PHONY: all top-all abc test install install-abc docs clean mrproper qtcreator coverage vcxsrc mxebin -.PHONY: config-clean config-clang config-gcc config-gcc-static config-afl-gcc config-gprof config-sudo +FORCE: + +.PHONY: all top-all abc test install-dev install install-abc docs clean mrproper qtcreator coverage vcxsrc +.PHONY: config-clean config-clang config-gcc config-gcc-static config-gprof config-sudo diff --git a/README.md b/README.md index d215d8442..71d47d76c 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,3 @@ -``` -yosys -- Yosys Open SYnthesis Suite - -Copyright (C) 2012 - 2024 Claire Xenia Wolf - -Permission to use, copy, modify, and/or distribute this software for any -purpose with or without fee is hereby granted, provided that the above -copyright notice and this permission notice appear in all copies. - -THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -``` - - yosys – Yosys Open SYnthesis Suite =================================== @@ -33,6 +14,10 @@ Yosys is free software licensed under the ISC license (a GPL compatible license that is similar in terms to the MIT license or the 2-clause BSD license). +Third-party software distributed alongside this software +is licensed under compatible licenses. +Please refer to `abc` and `libs` subdirectories for their license terms. + Web Site and Other Resources ============================ @@ -40,17 +25,14 @@ Web Site and Other Resources More information and documentation can be found on the Yosys web site: - https://yosyshq.net/yosys/ -The "Documentation" page on the web site contains links to more resources, -including a manual that even describes some of the Yosys internals: -- https://yosyshq.net/yosys/documentation.html +Documentation from this repository is automatically built and available on Read +the Docs: +- https://yosyshq.readthedocs.io/projects/yosys -The directory `guidelines` contains additional information -for people interested in using the Yosys C++ APIs. - -Users interested in formal verification might want to use the formal verification -front-end for Yosys, SymbiYosys: -- https://symbiyosys.readthedocs.io/en/latest/ -- https://github.com/YosysHQ/SymbiYosys +Users interested in formal verification might want to use the formal +verification front-end for Yosys, SBY: +- https://yosyshq.readthedocs.io/projects/sby/ +- https://github.com/YosysHQ/sby Installation @@ -68,9 +50,25 @@ For more information about the difference between Tabby CAD Suite and the OSS CA Many Linux distributions also provide Yosys binaries, some more up to date than others. Check with your package manager! + Building from Source ==================== +For more details, and instructions for other platforms, check [building from +source](https://yosyshq.readthedocs.io/projects/yosys/en/latest/getting_started/installation.html#building-from-source) +on Read the Docs. + +When cloning Yosys, some required libraries are included as git submodules. Make +sure to call e.g. + + $ git clone --recurse-submodules https://github.com/YosysHQ/yosys.git + +or + + $ git clone https://github.com/YosysHQ/yosys.git + $ cd yosys + $ git submodule update --init --recursive + You need a C++ compiler with C++17 support (up-to-date CLANG or GCC is recommended) and some standard tools such as GNU Flex, GNU Bison, and GNU Make. TCL, readline and libffi are optional (see ``ENABLE_*`` settings in Makefile). @@ -84,52 +82,22 @@ prerequisites for building yosys: graphviz xdot pkg-config python3 libboost-system-dev \ libboost-python-dev libboost-filesystem-dev zlib1g-dev -Similarily, on Mac OS X Homebrew can be used to install dependencies (from within cloned yosys repository): - - $ brew tap Homebrew/bundle && brew bundle - -or MacPorts: - - $ sudo port install bison flex readline gawk libffi \ - git graphviz pkgconfig python36 boost zlib tcl - -On FreeBSD use the following command to install all prerequisites: - - # pkg install bison flex readline gawk libffi\ - git graphviz pkgconf python3 python36 tcl-wrapper boost-libs - -On FreeBSD system use gmake instead of make. To run tests use: - % MAKE=gmake CC=cc gmake test - -For Cygwin use the following command to install all prerequisites, or select these additional packages: - - setup-x86_64.exe -q --packages=bison,flex,gcc-core,gcc-g++,git,libffi-devel,libreadline-devel,make,pkg-config,python3,tcl-devel,boost-build,zlib-devel - The environment variable `CXX` can be used to control the C++ compiler used, or -run one of the following: +run one of the following to override it: $ make config-clang $ make config-gcc -Note that these will result in `make` ignoring the `CXX` environment variable, -unless `CXX` is assigned in the call to make, e.g. +The Makefile has many variables influencing the build process. These can be +adjusted by modifying the Makefile.conf file which is created at the `make +config-...` step (see above), or they can be set by passing an option to the +make command directly: $ make CXX=$CXX -The Makefile has many variables influencing the build process. These can be -adjusted by modifying the Makefile.conf file which is created at the -`make config-...` step (see above), or they can be set by passing an option -to the make command directly. - -For example, if you have clang, and (a compatible version of) `ld.lld` -available in PATH, it's recommended to speed up incremental builds with -lld by enabling LTO: - - $ make ENABLE_LTO=1 - -For other compilers and build configurations it might be -necessary to make some changes to the config section of the -Makefile. +For other compilers and build configurations it might be necessary to make some +changes to the config section of the Makefile. It's also an alternative way to +set the make variables mentioned above. $ vi Makefile # ..or.. $ vi Makefile.conf @@ -139,10 +107,9 @@ To build Yosys simply type 'make' in this directory. $ make $ sudo make install -Note that this also downloads, builds and installs ABC (using yosys-abc -as executable name). - -Tests are located in the tests subdirectory and can be executed using the test target. Note that you need gawk as well as a recent version of iverilog (i.e. build from git). Then, execute tests via: +Tests are located in the tests subdirectory and can be executed using the test +target. Note that you need gawk as well as a recent version of iverilog (i.e. +build from git). Then, execute tests via: $ make test @@ -153,6 +120,7 @@ To use a separate (out-of-tree) build directory, provide a path to the Makefile. Out-of-tree builds require a clean source tree. + Getting Started =============== @@ -257,365 +225,14 @@ The command ``prep`` provides a good default word-level synthesis script, as used in SMT-based formal verification. -Unsupported Verilog-2005 Features -================================= - -The following Verilog-2005 features are not supported by -Yosys and there are currently no plans to add support -for them: - -- Non-synthesizable language features as defined in - IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002 - -- The ``tri``, ``triand`` and ``trior`` net types - -- The ``config`` and ``disable`` keywords and library map files - - -Verilog Attributes and non-standard features -============================================ - -- The ``full_case`` attribute on case statements is supported - (also the non-standard ``// synopsys full_case`` directive) - -- The ``parallel_case`` attribute on case statements is supported - (also the non-standard ``// synopsys parallel_case`` directive) - -- The ``// synopsys translate_off`` and ``// synopsys translate_on`` - directives are also supported (but the use of ``` `ifdef .. `endif ``` - is strongly recommended instead). - -- The ``nomem2reg`` attribute on modules or arrays prohibits the - automatic early conversion of arrays to separate registers. This - is potentially dangerous. Usually the front-end has good reasons - for converting an array to a list of registers. Prohibiting this - step will likely result in incorrect synthesis results. - -- The ``mem2reg`` attribute on modules or arrays forces the early - conversion of arrays to separate registers. - -- The ``nomeminit`` attribute on modules or arrays prohibits the - creation of initialized memories. This effectively puts ``mem2reg`` - on all memories that are written to in an ``initial`` block and - are not ROMs. - -- The ``nolatches`` attribute on modules or always-blocks - prohibits the generation of logic-loops for latches. Instead - all not explicitly assigned values default to x-bits. This does - not affect clocked storage elements such as flip-flops. - -- The ``nosync`` attribute on registers prohibits the generation of a - storage element. The register itself will always have all bits set - to 'x' (undefined). The variable may only be used as blocking assigned - temporary variable within an always block. This is mostly used internally - by Yosys to synthesize Verilog functions and access arrays. - -- The ``nowrshmsk`` attribute on a register prohibits the generation of - shift-and-mask type circuits for writing to bit slices of that register. - -- The ``onehot`` attribute on wires mark them as one-hot state register. This - is used for example for memory port sharing and set by the fsm_map pass. - -- The ``blackbox`` attribute on modules is used to mark empty stub modules - that have the same ports as the real thing but do not contain information - on the internal configuration. This modules are only used by the synthesis - passes to identify input and output ports of cells. The Verilog backend - also does not output blackbox modules on default. ``read_verilog``, unless - called with ``-noblackbox`` will automatically set the blackbox attribute - on any empty module it reads. - -- The ``noblackbox`` attribute set on an empty module prevents ``read_verilog`` - from automatically setting the blackbox attribute on the module. - -- The ``whitebox`` attribute on modules triggers the same behavior as - ``blackbox``, but is for whitebox modules, i.e. library modules that - contain a behavioral model of the cell type. - -- The ``lib_whitebox`` attribute overwrites ``whitebox`` when ``read_verilog`` - is run in `-lib` mode. Otherwise it's automatically removed. - -- The ``dynports`` attribute is used by the Verilog front-end to mark modules - that have ports with a width that depends on a parameter. - -- The ``hdlname`` attribute is used by some passes to document the original - (HDL) name of a module when renaming a module. It should contain a single - name, or, when describing a hierarchical name in a flattened design, multiple - names separated by a single space character. - -- The ``keep`` attribute on cells and wires is used to mark objects that should - never be removed by the optimizer. This is used for example for cells that - have hidden connections that are not part of the netlist, such as IO pads. - Setting the ``keep`` attribute on a module has the same effect as setting it - on all instances of the module. - -- The ``keep_hierarchy`` attribute on cells and modules keeps the ``flatten`` - command from flattening the indicated cells and modules. - -- The ``init`` attribute on wires is set by the frontend when a register is - initialized "FPGA-style" with ``reg foo = val``. It can be used during - synthesis to add the necessary reset logic. - -- The ``top`` attribute on a module marks this module as the top of the - design hierarchy. The ``hierarchy`` command sets this attribute when called - with ``-top``. Other commands, such as ``flatten`` and various backends - use this attribute to determine the top module. - -- The ``src`` attribute is set on cells and wires created by to the string - ``:`` by the HDL front-end and is then carried - through the synthesis. When entities are combined, a new |-separated - string is created that contains all the string from the original entities. - -- The ``defaultvalue`` attribute is used to store default values for - module inputs. The attribute is attached to the input wire by the HDL - front-end when the input is declared with a default value. - -- The ``parameter`` and ``localparam`` attributes are used to mark wires - that represent module parameters or localparams (when the HDL front-end - is run in ``-pwires`` mode). - -- Wires marked with the ``hierconn`` attribute are connected to wires with the - same name (format ``cell_name.identifier``) when they are imported from - sub-modules by ``flatten``. - -- The ``clkbuf_driver`` attribute can be set on an output port of a blackbox - module to mark it as a clock buffer output, and thus prevent ``clkbufmap`` - from inserting another clock buffer on a net driven by such output. - -- The ``clkbuf_sink`` attribute can be set on an input port of a module to - request clock buffer insertion by the ``clkbufmap`` pass. - -- The ``clkbuf_inv`` attribute can be set on an output port of a module - with the value set to the name of an input port of that module. When - the ``clkbufmap`` would otherwise insert a clock buffer on this output, - it will instead try inserting the clock buffer on the input port (this - is used to implement clock inverter cells that clock buffer insertion - will "see through"). - -- The ``clkbuf_inhibit`` is the default attribute to set on a wire to prevent - automatic clock buffer insertion by ``clkbufmap``. This behaviour can be - overridden by providing a custom selection to ``clkbufmap``. - -- The ``invertible_pin`` attribute can be set on a port to mark it as - invertible via a cell parameter. The name of the inversion parameter - is specified as the value of this attribute. The value of the inversion - parameter must be of the same width as the port, with 1 indicating - an inverted bit and 0 indicating a non-inverted bit. - -- The ``iopad_external_pin`` attribute on a blackbox module's port marks - it as the external-facing pin of an I/O pad, and prevents ``iopadmap`` - from inserting another pad cell on it. - -- The module attribute ``abc9_lut`` is an integer attribute indicating to - `abc9` that this module describes a LUT with an area cost of this value, and - propagation delays described using `specify` statements. - -- The module attribute ``abc9_box`` is a boolean specifying a black/white-box - definition, with propagation delays described using `specify` statements, for - use by `abc9`. - -- The port attribute ``abc9_carry`` marks the carry-in (if an input port) and - carry-out (if output port) ports of a box. This information is necessary for - `abc9` to preserve the integrity of carry-chains. Specifying this attribute - onto a bus port will affect only its most significant bit. - -- The module attribute ``abc9_flop`` is a boolean marking the module as a - flip-flop. This allows `abc9` to analyse its contents in order to perform - sequential synthesis. - -- The frontend sets attributes ``always_comb``, ``always_latch`` and - ``always_ff`` on processes derived from SystemVerilog style always blocks - according to the type of the always. These are checked for correctness in - ``proc_dlatch``. - -- The cell attribute ``wildcard_port_conns`` represents wildcard port - connections (SystemVerilog ``.*``). These are resolved to concrete - connections to matching wires in ``hierarchy``. - -- In addition to the ``(* ... *)`` attribute syntax, Yosys supports - the non-standard ``{* ... *}`` attribute syntax to set default attributes - for everything that comes after the ``{* ... *}`` statement. (Reset - by adding an empty ``{* *}`` statement.) - -- In module parameter and port declarations, and cell port and parameter - lists, a trailing comma is ignored. This simplifies writing Verilog code - generators a bit in some cases. - -- Modules can be declared with ``module mod_name(...);`` (with three dots - instead of a list of module ports). With this syntax it is sufficient - to simply declare a module port as 'input' or 'output' in the module - body. - -- When defining a macro with `define, all text between triple double quotes - is interpreted as macro body, even if it contains unescaped newlines. The - triple double quotes are removed from the macro body. For example: - - `define MY_MACRO(a, b) """ - assign a = 23; - assign b = 42; - """ - -- The attribute ``via_celltype`` can be used to implement a Verilog task or - function by instantiating the specified cell type. The value is the name - of the cell type to use. For functions the name of the output port can - be specified by appending it to the cell type separated by a whitespace. - The body of the task or function is unused in this case and can be used - to specify a behavioral model of the cell type for simulation. For example: - - module my_add3(A, B, C, Y); - parameter WIDTH = 8; - input [WIDTH-1:0] A, B, C; - output [WIDTH-1:0] Y; - ... - endmodule - - module top; - ... - (* via_celltype = "my_add3 Y" *) - (* via_celltype_defparam_WIDTH = 32 *) - function [31:0] add3; - input [31:0] A, B, C; - begin - add3 = A + B + C; - end - endfunction - ... - endmodule - -- The ``wiretype`` attribute is added by the verilog parser for wires of a - typedef'd type to indicate the type identifier. - -- Various ``enum_value_{value}`` attributes are added to wires of an enumerated type - to give a map of possible enum items to their values. - -- The ``enum_base_type`` attribute is added to enum items to indicate which - enum they belong to (enums -- anonymous and otherwise -- are - automatically named with an auto-incrementing counter). Note that enums - are currently not strongly typed. - -- A limited subset of DPI-C functions is supported. The plugin mechanism - (see ``help plugin``) can be used to load .so files with implementations - of DPI-C routines. As a non-standard extension it is possible to specify - a plugin alias using the ``:`` syntax. For example: - - module dpitest; - import "DPI-C" function foo:round = real my_round (real); - parameter real r = my_round(12.345); - endmodule - - $ yosys -p 'plugin -a foo -i /lib/libm.so; read_verilog dpitest.v' - -- Sized constants (the syntax ``'s?[bodh]``) support constant - expressions as ````. If the expression is not a simple identifier, it - must be put in parentheses. Examples: ``WIDTH'd42``, ``(4+2)'b101010`` - -- The system tasks ``$finish``, ``$stop`` and ``$display`` are supported in - initial blocks in an unconditional context (only if/case statements on - expressions over parameters and constant values are allowed). The intended - use for this is synthesis-time DRC. - -- There is limited support for converting ``specify`` .. ``endspecify`` - statements to special ``$specify2``, ``$specify3``, and ``$specrule`` cells, - for use in blackboxes and whiteboxes. Use ``read_verilog -specify`` to - enable this functionality. (By default these blocks are ignored.) - -- The ``reprocess_after`` internal attribute is used by the Verilog frontend to - mark cells with bindings which might depend on the specified instantiated - module. Modules with such cells will be reprocessed during the ``hierarchy`` - pass once the referenced module definition(s) become available. - -- The ``smtlib2_module`` attribute can be set on a blackbox module to specify a - formal model directly using SMT-LIB 2. For such a module, the - ``smtlib2_comb_expr`` attribute can be used on output ports to define their - value using an SMT-LIB 2 expression. For example: - - (* blackbox *) - (* smtlib2_module *) - module submod(a, b); - input [7:0] a; - (* smtlib2_comb_expr = "(bvnot a)" *) - output [7:0] b; - endmodule - -Non-standard or SystemVerilog features for formal verification -============================================================== - -- Support for ``assert``, ``assume``, ``restrict``, and ``cover`` is enabled - when ``read_verilog`` is called with ``-formal``. - -- The system task ``$initstate`` evaluates to 1 in the initial state and - to 0 otherwise. - -- The system function ``$anyconst`` evaluates to any constant value. This is - equivalent to declaring a reg as ``rand const``, but also works outside - of checkers. (Yosys also supports ``rand const`` outside checkers.) - -- The system function ``$anyseq`` evaluates to any value, possibly a different - value in each cycle. This is equivalent to declaring a reg as ``rand``, - but also works outside of checkers. (Yosys also supports ``rand`` - variables outside checkers.) - -- The system functions ``$allconst`` and ``$allseq`` can be used to construct - formal exist-forall problems. Assumptions only hold if the trace satisfies - the assumption for all ``$allconst/$allseq`` values. For assertions and cover - statements it is sufficient if just one ``$allconst/$allseq`` value triggers - the property (similar to ``$anyconst/$anyseq``). - -- Wires/registers declared using the ``anyconst/anyseq/allconst/allseq`` attribute - (for example ``(* anyconst *) reg [7:0] foobar;``) will behave as if driven - by a ``$anyconst/$anyseq/$allconst/$allseq`` function. - -- The SystemVerilog tasks ``$past``, ``$stable``, ``$rose`` and ``$fell`` are - supported in any clocked block. - -- The syntax ``@($global_clock)`` can be used to create FFs that have no - explicit clock input (``$ff`` cells). The same can be achieved by using - ``@(posedge )`` or ``@(negedge )`` when ```` - is marked with the ``(* gclk *)`` Verilog attribute. - - -Supported features from SystemVerilog -===================================== - -When ``read_verilog`` is called with ``-sv``, it accepts some language features -from SystemVerilog: - -- The ``assert`` statement from SystemVerilog is supported in its most basic - form. In module context: ``assert property ();`` and within an - always block: ``assert();``. It is transformed to an ``$assert`` cell. - -- The ``assume``, ``restrict``, and ``cover`` statements from SystemVerilog are - also supported. The same limitations as with the ``assert`` statement apply. - -- The keywords ``always_comb``, ``always_ff`` and ``always_latch``, ``logic`` - and ``bit`` are supported. - -- Declaring free variables with ``rand`` and ``rand const`` is supported. - -- Checkers without a port list that do not need to be instantiated (but instead - behave like a named block) are supported. - -- SystemVerilog packages are supported. Once a SystemVerilog file is read - into a design with ``read_verilog``, all its packages are available to - SystemVerilog files being read into the same design afterwards. - -- typedefs are supported (including inside packages) - - type casts are currently not supported - -- enums are supported (including inside packages) - - but are currently not strongly typed - -- packed structs and unions are supported - - arrays of packed structs/unions are currently not supported - - structure literals are currently not supported - -- multidimensional arrays are supported - - array assignment of unpacked arrays is currently not supported - - array literals are currently not supported - -- SystemVerilog interfaces (SVIs) are supported. Modports for specifying whether - ports are inputs or outputs are supported. - -- Assignments within expressions are supported. +Additional information +====================== + +The ``read_verilog`` command, used by default when calling ``read`` with Verilog +source input, does not perform syntax checking. You should instead lint your +source with another tool such as +[Verilator](https://www.veripool.org/verilator/) first, e.g. by calling +``verilator --lint-only``. Building the documentation diff --git a/abc b/abc index 2188bc712..fcd8ac34d 160000 --- a/abc +++ b/abc @@ -1 +1 @@ -Subproject commit 2188bc71228b0788569d83ad2b7e7b91ca5dcc09 +Subproject commit fcd8ac34d6105b48f32dfaf31983b071c46fb7b9 diff --git a/backends/aiger/aiger.cc b/backends/aiger/aiger.cc index f2cb5d9bc..e8b8e32ce 100644 --- a/backends/aiger/aiger.cc +++ b/backends/aiger/aiger.cc @@ -132,7 +132,7 @@ struct AigerWriter return a; } - AigerWriter(Module *module, bool zinit_mode, bool imode, bool omode, bool bmode, bool lmode) : module(module), zinit_mode(zinit_mode), sigmap(module) + AigerWriter(Module *module, bool no_sort, bool zinit_mode, bool imode, bool omode, bool bmode, bool lmode) : module(module), zinit_mode(zinit_mode), sigmap(module) { pool undriven_bits; pool unused_bits; @@ -152,6 +152,37 @@ struct AigerWriter if (wire->port_input) sigmap.add(wire); + // handle ports + // provided the input_bits and output_bits don't get sorted they + // will be returned in reverse order, so add them in reverse to + // match + for (auto riter = module->ports.rbegin(); riter != module->ports.rend(); ++riter) { + auto *wire = module->wire(*riter); + for (int i = 0; i < GetSize(wire); i++) + { + SigBit wirebit(wire, i); + SigBit bit = sigmap(wirebit); + + if (bit.wire == nullptr) { + if (wire->port_output) { + aig_map[wirebit] = (bit == State::S1) ? 1 : 0; + output_bits.insert(wirebit); + } + continue; + } + + if (wire->port_input) + input_bits.insert(bit); + + if (wire->port_output) { + if (bit != wirebit) + alias_map[wirebit] = bit; + output_bits.insert(wirebit); + } + } + } + + // handle wires for (auto wire : module->wires()) { if (wire->attributes.count(ID::init)) { @@ -167,25 +198,13 @@ struct AigerWriter SigBit wirebit(wire, i); SigBit bit = sigmap(wirebit); - if (bit.wire == nullptr) { - if (wire->port_output) { - aig_map[wirebit] = (bit == State::S1) ? 1 : 0; - output_bits.insert(wirebit); - } + if (bit.wire == nullptr) + continue; + if (wire->port_input || wire->port_output) continue; - } undriven_bits.insert(bit); unused_bits.insert(bit); - - if (wire->port_input) - input_bits.insert(bit); - - if (wire->port_output) { - if (bit != wirebit) - alias_map[wirebit] = bit; - output_bits.insert(wirebit); - } } if (wire->width == 1) { @@ -200,12 +219,6 @@ struct AigerWriter } } - for (auto bit : input_bits) - undriven_bits.erase(bit); - - for (auto bit : output_bits) - unused_bits.erase(bit); - for (auto cell : module->cells()) { if (cell->type == ID($_NOT_)) @@ -343,8 +356,11 @@ struct AigerWriter } init_map.sort(); - input_bits.sort(); - output_bits.sort(); + // we are relying here on unsorted pools iterating last-in-first-out + if (!no_sort) { + input_bits.sort(); + output_bits.sort(); + } not_map.sort(); ff_map.sort(); and_map.sort(); @@ -662,8 +678,7 @@ struct AigerWriter f << std::endl; } } - - f << stringf("c\nGenerated by %s\n", yosys_version_str); + f << stringf("c\nGenerated by %s\n", yosys_maybe_version()); } void write_map(std::ostream &f, bool verbose_map, bool no_startoffset) @@ -698,7 +713,7 @@ struct AigerWriter } if (wire->port_output) { - int o = ordered_outputs.at(sig[i]); + int o = ordered_outputs.at(SigSpec(wire, i)); output_lines[o] += stringf("output %d %d %s\n", o, index, log_id(wire)); } @@ -746,7 +761,7 @@ struct AigerWriter { json.begin_object(); json.entry("version", "Yosys Witness Aiger map"); - json.entry("gennerator", yosys_version_str); + json.entry("gennerator", yosys_maybe_version()); json.entry("latch_count", aig_l); json.entry("input_count", aig_i); @@ -902,6 +917,9 @@ struct AigerBackend : public Backend { log(" -symbols\n"); log(" include a symbol table in the generated AIGER file\n"); log("\n"); + log(" -no-sort\n"); + log(" don't sort input/output ports\n"); + log("\n"); log(" -map \n"); log(" write an extra file with port and latch symbols\n"); log("\n"); @@ -926,6 +944,7 @@ struct AigerBackend : public Backend { bool zinit_mode = false; bool miter_mode = false; bool symbols_mode = false; + bool no_sort = false; bool verbose_map = false; bool imode = false; bool omode = false; @@ -956,6 +975,10 @@ struct AigerBackend : public Backend { symbols_mode = true; continue; } + if (args[argidx] == "-no-sort") { + no_sort = true; + continue; + } if (map_filename.empty() && args[argidx] == "-map" && argidx+1 < args.size()) { map_filename = args[++argidx]; continue; @@ -1009,7 +1032,7 @@ struct AigerBackend : public Backend { if (!top_module->memories.empty()) log_error("Found unmapped memories in module %s: unmapped memories are not supported in AIGER backend!\n", log_id(top_module)); - AigerWriter writer(top_module, zinit_mode, imode, omode, bmode, lmode); + AigerWriter writer(top_module, no_sort, zinit_mode, imode, omode, bmode, lmode); writer.write_aiger(*f, ascii_mode, miter_mode, symbols_mode); if (!map_filename.empty()) { diff --git a/backends/aiger/xaiger.cc b/backends/aiger/xaiger.cc index 3ca8b205a..97dec40e4 100644 --- a/backends/aiger/xaiger.cc +++ b/backends/aiger/xaiger.cc @@ -53,6 +53,8 @@ struct XAigerWriter dict arrival_times; vector> aig_gates; + vector bit2aig_stack; + int next_loop_check = 1024; vector aig_outputs; int aig_m = 0, aig_i = 0, aig_l = 0, aig_o = 0, aig_a = 0; @@ -76,6 +78,24 @@ struct XAigerWriter return it->second; } + if (GetSize(bit2aig_stack)== next_loop_check) { + for (int i = 0; i < next_loop_check; ++i) + { + SigBit report_bit = bit2aig_stack[i]; + if (report_bit != bit) + continue; + for (int j = i; j < next_loop_check; ++j) { + report_bit = bit2aig_stack[j]; + if (report_bit.is_wire() && report_bit.wire->name.isPublic()) + break; + } + log_error("Found combinatorial logic loop while processing signal %s.\n", log_signal(report_bit)); + } + next_loop_check *= 2; + } + + bit2aig_stack.push_back(bit); + // NB: Cannot use iterator returned from aig_map.insert() // since this function is called recursively @@ -93,6 +113,8 @@ struct XAigerWriter a = bit2aig(alias_map.at(bit)); } + bit2aig_stack.pop_back(); + if (bit == State::Sx || bit == State::Sz) { log_debug("Design contains 'x' or 'z' bits. Treating as 1'b0.\n"); a = aig_map.at(State::S0); @@ -649,7 +671,7 @@ struct XAigerWriter //f.write(reinterpret_cast(&buffer_size_be), sizeof(buffer_size_be)); //f.write(buffer_str.data(), buffer_str.size()); - f << stringf("Generated by %s\n", yosys_version_str); + f << stringf("Generated by %s\n", yosys_maybe_version()); design->scratchpad_set_int("write_xaiger.num_ands", and_map.size()); design->scratchpad_set_int("write_xaiger.num_wires", aig_map.size()); diff --git a/backends/aiger2/Makefile.inc b/backends/aiger2/Makefile.inc new file mode 100644 index 000000000..494b8d6c6 --- /dev/null +++ b/backends/aiger2/Makefile.inc @@ -0,0 +1 @@ +OBJS += backends/aiger2/aiger.o diff --git a/backends/aiger2/aiger.cc b/backends/aiger2/aiger.cc new file mode 100644 index 000000000..c7ed3b81f --- /dev/null +++ b/backends/aiger2/aiger.cc @@ -0,0 +1,1464 @@ +/* + * yosys -- Yosys Open SYnthesis Suite + * + * Copyright (C) Martin Povišer + * + * Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + * + */ + +// TODOs: +// - gracefully handling inout ports (an error message probably) +// - undriven wires +// - zero-width operands + +#include "kernel/register.h" +#include "kernel/celltypes.h" + +USING_YOSYS_NAMESPACE +PRIVATE_NAMESPACE_BEGIN + +#define BITWISE_OPS ID($buf), ID($not), ID($mux), ID($and), ID($or), ID($xor), ID($xnor), ID($fa), \ + ID($bwmux) + +#define REDUCE_OPS ID($reduce_and), ID($reduce_or), ID($reduce_xor), ID($reduce_xnor), ID($reduce_bool) + +#define LOGIC_OPS ID($logic_and), ID($logic_or), ID($logic_not) + +#define GATE_OPS ID($_BUF_), ID($_NOT_), ID($_AND_), ID($_NAND_), ID($_OR_), ID($_NOR_), \ + ID($_XOR_), ID($_XNOR_), ID($_ANDNOT_), ID($_ORNOT_), ID($_MUX_), ID($_NMUX_), \ + ID($_AOI3_), ID($_OAI3_), ID($_AOI4_), ID($_OAI4_) + +#define CMP_OPS ID($eq), ID($ne), ID($lt), ID($le), ID($ge), ID($gt) + +// TODO +//#define ARITH_OPS ID($add), ID($sub), ID($neg) + +#define KNOWN_OPS BITWISE_OPS, REDUCE_OPS, LOGIC_OPS, GATE_OPS, ID($pos), CMP_OPS, \ + ID($pmux), ID($bmux) /*, ARITH_OPS*/ + +template +struct Index { + struct HierCursor; + struct ModuleInfo { + Module *module; + int len; + dict windices; + dict suboffsets; + pool found_blackboxes; + + bool indexing = false; + bool indexed = false; + }; + + dict modules; + + int index_wires(ModuleInfo &info, RTLIL::Module *m) + { + int sum = 0; + for (auto w : m->wires()) { + info.windices[w] = sum; + sum += w->width; + } + return sum; + } + + bool flatten = false; + bool inline_whiteboxes = false; + bool allow_blackboxes = false; + + int index_module(RTLIL::Module *m) + { + ModuleInfo &info = modules[m]; + + if (info.indexed) + return info.len; + + if (info.indexing && !info.indexed) + log_error("Hierarchy error\n"); + + info.module = m; + int pos = index_wires(info, m); + + for (auto cell : m->cells()) { + if (cell->type.in(KNOWN_OPS) || cell->type.in(ID($scopeinfo), ID($specify2), ID($specify3))) + continue; + + Module *submodule = m->design->module(cell->type); + + if (submodule && flatten && + !submodule->get_bool_attribute(ID::keep_hierarchy) && + !submodule->get_blackbox_attribute(inline_whiteboxes)) { + info.suboffsets[cell] = pos; + pos += index_module(submodule); + } else { + if (allow_blackboxes) { + info.found_blackboxes.insert(cell); + } else { + if (!submodule || submodule->get_blackbox_attribute()) + log_error("Unsupported cell type: %s (%s in %s)\n", + log_id(cell->type), log_id(cell), log_id(m)); + } + } + } + + info.len = pos; + return info.len; + } + + Design *design; + Module *top; + ModuleInfo *top_minfo; + std::vector lits; + + Index() + { + } + + void setup(RTLIL::Module *top) + { + design = top->design; + this->top = top; + + modules.reserve(top->design->modules().size()); + int nlits = index_module(top); + log_debug("allocating for %d literals\n", nlits); + lits.resize(nlits, Writer::EMPTY_LIT); + top_minfo = &modules.at(top); + } + + bool const_folding = true; + bool strashing = false; + dict, Lit> cache; + + Lit AND(Lit a, Lit b) + { + if (const_folding) { + if (a == CFALSE || b == CFALSE) + return CFALSE; + if (a == CTRUE) + return b; + if (b == CTRUE) + return a; + } + + if (!strashing) { + return (static_cast(this))->emit_gate(a, b); + } else { + if (a < b) std::swap(a, b); + auto pair = std::make_pair(a, b); + + if (!cache.count(pair)) { + Lit nl = (static_cast(this))->emit_gate(a, b); + cache[pair] = nl; + return nl; + } else { + return cache.at(pair); + } + } + } + + Lit NOT(Lit lit) + { + return Writer::negate(lit); + } + + Lit OR(Lit a, Lit b) + { + return NOT(AND(NOT(a), NOT(b))); + } + + Lit MUX(Lit a, Lit b, Lit s) + { + if (const_folding) { + if (a == b) + return a; + if (s == CFALSE) + return a; + if (s == CTRUE) + return b; + } + + return OR(AND(a, NOT(s)), AND(b, s)); + } + + Lit XOR(Lit a, Lit b) + { + return OR(AND(a, NOT(b)), AND(NOT(a), b)); + } + + Lit XNOR(Lit a, Lit b) + { + return NOT(OR(AND(a, NOT(b)), AND(NOT(a), b))); + } + + Lit CARRY(Lit a, Lit b, Lit c) + { + if (const_folding) { + if (c == CTRUE) { + return OR(a, b); + } else if (c == CFALSE) { + return AND(a, b); + } + } + return OR(AND(a, b), AND(c, OR(a, b))); + } + + Lit REDUCE(std::vector lits, bool op_xor=false) + { + std::vector next; + while (lits.size() > 1) { + next.clear(); + for (int i = 0; i < (int) lits.size(); i += 2) { + if (i + 1 >= (int) lits.size()) { + next.push_back(lits[i]); + } else { + Lit a = lits[i], b = lits[i + 1]; + next.push_back(op_xor ? XOR(a, b) : AND(a, b)); + } + } + next.swap(lits); + } + + if (lits.empty()) + return op_xor ? CFALSE : CTRUE; + else + return lits.front(); + } + + Lit impl_op(HierCursor &cursor, Cell *cell, IdString oport, int obit) + { + if (cell->type.in(REDUCE_OPS, LOGIC_OPS, CMP_OPS) && obit != 0) { + return CFALSE; + } else if (cell->type.in(CMP_OPS)) { + SigSpec aport = cell->getPort(ID::A); + bool asigned = cell->getParam(ID::A_SIGNED).as_bool(); + SigSpec bport = cell->getPort(ID::B); + bool bsigned = cell->getParam(ID::B_SIGNED).as_bool(); + + int width = std::max(aport.size(), bport.size()) + 1; + aport.extend_u0(width, asigned); + bport.extend_u0(width, bsigned); + + if (cell->type.in(ID($eq), ID($ne))) { + int carry = CTRUE; + for (int i = 0; i < width; i++) { + Lit a = visit(cursor, aport[i]); + Lit b = visit(cursor, bport[i]); + carry = AND(carry, XNOR(a, b)); + } + return (cell->type == ID($eq)) ? carry : /* $ne */ NOT(carry); + } else if (cell->type.in(ID($lt), ID($le), ID($gt), ID($ge))) { + if (cell->type.in(ID($gt), ID($ge))) + std::swap(aport, bport); + int carry = cell->type.in(ID($le), ID($ge)) ? CFALSE : CTRUE; + Lit a = Writer::EMPTY_LIT; + Lit b = Writer::EMPTY_LIT; + // TODO: this might not be the most economic structure; revisit at a later date + for (int i = 0; i < width; i++) { + a = visit(cursor, aport[i]); + b = visit(cursor, bport[i]); + if (i != width - 1) + carry = CARRY(a, NOT(b), carry); + } + return XOR(carry, XNOR(a, b)); + } else { + log_abort(); + } + } else if (cell->type.in(REDUCE_OPS, ID($logic_not))) { + SigSpec inport = cell->getPort(ID::A); + + std::vector lits; + for (int i = 0; i < inport.size(); i++) { + Lit lit = visit(cursor, inport[i]); + if (cell->type.in(ID($reduce_and), ID($reduce_xor), ID($reduce_xnor))) { + lits.push_back(lit); + } else if (cell->type.in(ID($reduce_or), ID($reduce_bool), ID($logic_not))) { + lits.push_back(NOT(lit)); + } else { + log_abort(); + } + } + + Lit acc = REDUCE(lits, cell->type.in(ID($reduce_xor), ID($reduce_xnor))); + + if (!cell->type.in(ID($reduce_xnor), ID($reduce_or), ID($reduce_bool))) + return acc; + else + return NOT(acc); + } else if (cell->type.in(ID($logic_and), ID($logic_or))) { + SigSpec aport = cell->getPort(ID::A); + SigSpec bport = cell->getPort(ID::B); + + log_assert(aport.size() > 0 && bport.size() > 0); // TODO + + Lit a = visit(cursor, aport[0]); + for (int i = 1; i < aport.size(); i++) { + Lit l = visit(cursor, aport[i]); + a = OR(a, l); + } + + Lit b = visit(cursor, bport[0]); + for (int i = 1; i < bport.size(); i++) { + Lit l = visit(cursor, bport[i]); + b = OR(b, l); + } + + if (cell->type == ID($logic_and)) + return AND(a, b); + else if (cell->type == ID($logic_or)) + return OR(a, b); + else + log_abort(); + } else if (cell->type.in(BITWISE_OPS, GATE_OPS, ID($pos))) { + SigSpec aport = cell->getPort(ID::A); + Lit a; + if (obit < aport.size()) { + a = visit(cursor, aport[obit]); + } else { + if (cell->getParam(ID::A_SIGNED).as_bool()) + a = visit(cursor, aport.msb()); + else + a = CFALSE; + } + + if (cell->type.in(ID($buf), ID($pos), ID($_BUF_))) { + return a; + } else if (cell->type.in(ID($not), ID($_NOT_))) { + return NOT(a); + } else { + SigSpec bport = cell->getPort(ID::B); + Lit b; + if (obit < bport.size()) { + b = visit(cursor, bport[obit]); + } else { + if (cell->getParam(ID::B_SIGNED).as_bool()) + b = visit(cursor, bport.msb()); + else + b = CFALSE; + } + + if (cell->type.in(ID($and), ID($_AND_))) { + return AND(a, b); + } else if (cell->type.in(ID($_NAND_))) { + return NOT(AND(a, b)); + } else if (cell->type.in(ID($or), ID($_OR_))) { + return OR(a, b); + } else if (cell->type.in(ID($_NOR_))) { + return NOT(OR(a, b)); + } else if (cell->type.in(ID($xor), ID($_XOR_))) { + return XOR(a, b); + } else if (cell->type.in(ID($xnor), ID($_XNOR_))) { + return NOT(XOR(a, b)); + } else if (cell->type.in(ID($_ANDNOT_))) { + return AND(a, NOT(b)); + } else if (cell->type.in(ID($_ORNOT_))) { + return OR(a, NOT(b)); + } else if (cell->type.in(ID($mux), ID($_MUX_))) { + Lit s = visit(cursor, cell->getPort(ID::S)); + return MUX(a, b, s); + } else if (cell->type.in(ID($bwmux))) { + Lit s = visit(cursor, cell->getPort(ID::S)[obit]); + return MUX(a, b, s); + } else if (cell->type.in(ID($_NMUX_))) { + Lit s = visit(cursor, cell->getPort(ID::S)[obit]); + return NOT(MUX(a, b, s)); + } else if (cell->type.in(ID($fa))) { + Lit c = visit(cursor, cell->getPort(ID::C)[obit]); + Lit ab = XOR(a, b); + if (oport == ID::Y) { + return XOR(ab, c); + } else /* oport == ID::X */ { + return OR(AND(a, b), AND(c, ab)); + } + } else if (cell->type.in(ID($_AOI3_), ID($_OAI3_), ID($_AOI4_), ID($_OAI4_))) { + Lit c, d; + + c = visit(cursor, cell->getPort(ID::C)[obit]); + if (/* 4 input types */ cell->type.in(ID($_AOI4_), ID($_OAI4_))) + d = visit(cursor, cell->getPort(ID::D)[obit]); + else + d = cell->type == ID($_AOI3_) ? CTRUE : CFALSE; + + if (/* aoi */ cell->type.in(ID($_AOI3_), ID($_AOI4_))) + return NOT(OR(AND(a, b), AND(c, d))); + else + return NOT(AND(OR(a, b), OR(c, d))); + } else { + log_abort(); + } + } + } else if (cell->type == ID($pmux)) { + SigSpec aport = cell->getPort(ID::A); + SigSpec bport = cell->getPort(ID::B); + SigSpec sport = cell->getPort(ID::S); + int width = aport.size(); + + Lit a = visit(cursor, aport[obit]); + + std::vector bar, sels; + for (int i = 0; i < sport.size(); i++) { + Lit s = visit(cursor, sport[i]); + Lit b = visit(cursor, bport[width * i + obit]); + bar.push_back(NOT(AND(s, b))); + sels.push_back(NOT(s)); + } + + return OR(AND(REDUCE(sels), a), NOT(REDUCE(bar))); + } else if (cell->type == ID($bmux)) { + SigSpec aport = cell->getPort(ID::A); + SigSpec sport = cell->getPort(ID::S); + int width = cell->getParam(ID::WIDTH).as_int(); + + std::vector data; + for (int i = obit; i < aport.size(); i += width) + data.push_back(visit(cursor, aport[i])); + + std::vector next; + for (int i = 0; i < sport.size(); i++) { + Lit s = visit(cursor, sport[i]); + next.clear(); + for (int j = 0; j < (int) data.size(); j += 2) + next.push_back(MUX(data[j], data[j + 1], s)); + data.swap(next); + } + log_assert(data.size() == 1); + return data[0]; + } else { + log_abort(); + } + } + + struct HierCursor { + typedef std::pair Level; + std::vector levels; + int instance_offset = 0; + + HierCursor() + { + } + + ModuleInfo &leaf_minfo(Index &index) + { + if (levels.empty()) + return *index.top_minfo; + else + return levels.back().first; + } + + Module *leaf_module(Index &index) + { + return leaf_minfo(index).module; + } + + int bitwire_index(Index &index, SigBit bit) + { + log_assert(bit.wire != nullptr); + return instance_offset + leaf_minfo(index).windices[bit.wire] + bit.offset; + } + + Cell *exit(Index &index) + { + log_assert(!levels.empty()); + Cell *instance = levels.back().second; + + levels.pop_back(); + instance_offset -= leaf_minfo(index).suboffsets.at(instance); + + // return the instance we just exited + return instance; + } + + Module *enter(Index &index, Cell *cell) + { + Design *design = index.design; + auto &minfo = leaf_minfo(index); + log_assert(minfo.suboffsets.count(cell)); + Module *def = design->module(cell->type); + log_assert(def); + levels.push_back(Level(index.modules.at(def), cell)); + instance_offset += minfo.suboffsets.at(cell); + + // return the module definition we just entered + return def; + } + + bool is_top() + { + return levels.empty(); + } + + std::string path() + { + std::string ret; + bool first = true; + for (auto pair : levels) { + if (!first) + ret += "."; + if (!pair.second) + ret += RTLIL::unescape_id(pair.first.module->name); + else + ret += RTLIL::unescape_id(pair.second->name); + first = false; + } + return ret; + } + + int hash() const + { + int hash = 0; + for (auto pair : levels) + hash += (uintptr_t) pair.second; + return hash; + } + + bool operator==(const HierCursor &other) const + { + if (levels.size() != other.levels.size()) + return false; + + for (int i = 0; i < levels.size(); i++) + if (levels[i].second != other.levels[i].second) + return false; + + return true; + } + }; + + bool visit_hook(int, HierCursor&, SigBit) + { + return false; + } + + Lit visit(HierCursor &cursor, SigBit bit) + { + if (!bit.wire) { + if (bit == State::S1) + return CTRUE; + else if (bit == State::S0) + return CFALSE; + else if (bit == State::Sx) + return CFALSE; + else + log_error("Unhandled state %s\n", log_signal(bit)); + } + + int idx = cursor.bitwire_index(*this, bit); + if (lits[idx] != Writer::EMPTY_LIT) { + // literal already assigned + return lits[idx]; + } + + // provide means for the derived class to override + // the visit behavior + if ((static_cast(this))->visit_hook(idx, cursor, bit)) { + return lits[idx]; + } + + Lit ret; + if (!bit.wire->port_input) { + // an output of a cell + Cell *driver = bit.wire->driverCell(); + + if (driver->type.in(KNOWN_OPS)) { + ret = impl_op(cursor, driver, bit.wire->driverPort(), bit.offset); + } else { + Module *def = cursor.enter(*this, driver); + { + IdString portname = bit.wire->driverPort(); + Wire *w = def->wire(portname); + if (!w) + log_error("Output port %s on instance %s of %s doesn't exist\n", + log_id(portname), log_id(driver), log_id(def)); + if (bit.offset >= w->width) + log_error("Bit position %d of output port %s on instance %s of %s is out of range (port has width %d)\n", + bit.offset, log_id(portname), log_id(driver), log_id(def), w->width); + ret = visit(cursor, SigBit(w, bit.offset)); + } + cursor.exit(*this); + } + } else { + // a module input: we cannot be the top module, otherwise + // the branch for pre-existing literals would have been taken + log_assert(!cursor.is_top()); + + // step into the upper module + Cell *instance = cursor.exit(*this); + { + IdString portname = bit.wire->name; + if (!instance->hasPort(portname)) + log_error("Input port %s on instance %s of %s unconnected\n", + log_id(portname), log_id(instance), log_id(instance->type)); + auto &port = instance->getPort(portname); + if (bit.offset >= port.size()) + log_error("Bit %d of input port %s on instance %s of %s unconnected\n", + bit.offset, log_id(portname), log_id(instance), log_id(instance->type)); + ret = visit(cursor, port[bit.offset]); + } + cursor.enter(*this, instance); + } + + lits[idx] = ret; + return ret; + } + + Lit &pi_literal(SigBit bit, HierCursor *cursor=nullptr) + { + log_assert(bit.wire); + + if (!cursor) { + log_assert(bit.wire->module == top); + log_assert(bit.wire->port_input); + return lits[top_minfo->windices[bit.wire] + bit.offset]; + } else { + log_assert(bit.wire->module == cursor->leaf_module(*this)); + return lits[cursor->bitwire_index(*this, bit)]; + } + } + + Lit eval_po(SigBit bit, HierCursor *cursor=nullptr) + { + Lit ret; + if (!cursor) { + HierCursor cursor_; + ret = visit(cursor_, bit); + log_assert(cursor_.is_top()); + log_assert(cursor_.instance_offset == 0); + } else { + ret = visit(*cursor, bit); + } + return ret; + } + + void visit_hierarchy(std::function f, + HierCursor &cursor) + { + f(cursor); + + ModuleInfo &minfo = cursor.leaf_minfo(*this); + for (auto cell : minfo.module->cells()) { + if (minfo.suboffsets.count(cell)) { + cursor.enter(*this, cell); + visit_hierarchy(f, cursor); + cursor.exit(*this); + } + } + } + + void visit_hierarchy(std::function f) + { + HierCursor cursor; + visit_hierarchy(f, cursor); + } +}; + +struct AigerWriter : Index { + typedef unsigned int Lit; + + const static constexpr Lit EMPTY_LIT = std::numeric_limits::max(); + + static Lit negate(Lit lit) { + return lit ^ 1; + } + + std::ostream *f; + Lit lit_counter; + int ninputs, nlatches, noutputs, nands; + + void encode(int delta) + { + log_assert(delta >= 0); + unsigned int x = delta; + while (x & ~0x7f) { + f->put((x & 0x7f) | 0x80); + x = x >> 7; + } + f->put(x); + } + + Lit emit_gate(Lit a, Lit b) + { + Lit out = lit_counter; + nands++; + lit_counter += 2; + + if (a < b) std::swap(a, b); + encode(out - a); + encode(a - b); + return out; + } + + void reset_counters() + { + lit_counter = 2; + ninputs = nlatches = noutputs = nands = 0; + } + + void write_header() { + log_assert(lit_counter == (Lit) (ninputs + nlatches + nands) * 2 + 2); + + char buf[128]; + snprintf(buf, sizeof(buf) - 1, "aig %08d %08d %08d %08d %08d\n", + ninputs + nlatches + nands, ninputs, nlatches, noutputs, nands); + f->write(buf, strlen(buf)); + } + + void write(std::ostream *f) { + reset_counters(); + + auto file_start = f->tellp(); + + // populate inputs + std::vector inputs; + for (auto id : top->ports) { + Wire *w = top->wire(id); + log_assert(w); + if (w->port_input) + for (int i = 0; i < w->width; i++) { + pi_literal(SigBit(w, i)) = lit_counter; + inputs.push_back(SigBit(w, i)); + lit_counter += 2; + ninputs++; + } + } + + this->f = f; + // start with the header + write_header(); + // insert padding where output literals will go (once known) + for (auto id : top->ports) { + Wire *w = top->wire(id); + log_assert(w); + if (w->port_output) { + for (auto bit : SigSpec(w)) { + (void) bit; + char buf[16]; + snprintf(buf, sizeof(buf) - 1, "%08d\n", 0); + f->write(buf, strlen(buf)); + noutputs++; + } + } + } + auto data_start = f->tellp(); + + // now the guts + std::vector> outputs; + for (auto w : top->wires()) + if (w->port_output) { + for (auto bit : SigSpec(w)) + outputs.push_back({bit, eval_po(bit)}); + } + auto data_end = f->tellp(); + + // revisit header and the list of outputs + f->seekp(file_start); + write_header(); + for (auto pair : outputs) { + char buf[16]; + snprintf(buf, sizeof(buf) - 1, "%08d\n", pair.second); + f->write(buf, strlen(buf)); + } + // double check we arrived at the same offset for the + // main data section + log_assert(data_start == f->tellp()); + + f->seekp(data_end); + int i = 0; + for (auto pair : outputs) { + if (SigSpec(pair.first).is_wire()) { + char buf[32]; + snprintf(buf, sizeof(buf) - 1, "o%d ", i); + f->write(buf, strlen(buf)); + std::string name = RTLIL::unescape_id(pair.first.wire->name); + f->write(name.data(), name.size()); + f->put('\n'); + } + i++; + } + i = 0; + for (auto bit : inputs) { + if (SigSpec(bit).is_wire()) { + char buf[32]; + snprintf(buf, sizeof(buf) - 1, "i%d ", i); + f->write(buf, strlen(buf)); + std::string name = RTLIL::unescape_id(bit.wire->name); + f->write(name.data(), name.size()); + f->put('\n'); + } + i++; + } + } +}; + +struct XAigerAnalysis : Index { + const static constexpr int EMPTY_LIT = -1; + + XAigerAnalysis() + { + allow_blackboxes = true; + + // Disable const folding and strashing as literal values are not unique + const_folding = false; + strashing = false; + } + + static int negate(int lit) + { + return lit; + } + + int emit_gate(int a, int b) + { + return max(a, b) + 1; + } + + pool seen; + + bool visit_hook(int idx, HierCursor &cursor, SigBit bit) + { + log_assert(cursor.is_top()); // TOOD: fix analyzer to work with hierarchy + + if (bit.wire->port_input) + return false; + + Cell *driver = bit.wire->driverCell(); + Module *mod = design->module(driver->type); + if (!mod || !mod->has_attribute(ID::abc9_box_id)) + return false; + + int max = 1; + for (auto wire : mod->wires()) + if (wire->port_input) + for (int i = 0; i < wire->width; i++) { + int ilevel = visit(cursor, driver->getPort(wire->name)[i]); + max = std::max(max, ilevel + 1); + } + lits[idx] = max; + + if (!seen.count(driver)) + seen.insert(driver); + + return true; + } + + void analyze(Module *top) + { + setup(top); + + for (auto id : top->ports) { + Wire *w = top->wire(id); + log_assert(w); + if (w->port_input) + for (int i = 0; i < w->width; i++) + pi_literal(SigBit(w, i)) = 0; + } + + HierCursor cursor; + for (auto box : top_minfo->found_blackboxes) { + Module *def = design->module(box->type); + if (!(def && def->has_attribute(ID::abc9_box_id))) + for (auto &conn : box->connections_) + if (box->output(conn.first)) + for (auto bit : conn.second) + pi_literal(bit, &cursor) = 0; + } + + for (auto w : top->wires()) + if (w->port_output) { + for (auto bit : SigSpec(w)) + (void) eval_po(bit); + } + + for (auto box : top_minfo->found_blackboxes) { + Module *def = design->module(box->type); + if (!(def && def->has_attribute(ID::abc9_box_id))) + for (auto &conn : box->connections_) + if (box->input(conn.first)) + for (auto bit : conn.second) + (void) eval_po(bit); + } + } +}; + +struct XAigerWriter : AigerWriter { + XAigerWriter() + { + allow_blackboxes = true; + } + + bool mapping_prep = false; + pool keep_wires; + std::ofstream map_file; + + typedef std::pair HierBit; + std::vector pos; + std::vector pis; + int proper_pos_counter = 0; + + pool driven_by_opaque_box; + + void ensure_pi(SigBit bit, HierCursor cursor={}, + bool box_port=false) + { + Lit &lit = pi_literal(bit, &cursor); + if (lit == EMPTY_LIT) { + lit = lit_counter; + pis.push_back(std::make_pair(bit, cursor)); + lit_counter += 2; + if (map_file.is_open() && !box_port) { + log_assert(cursor.is_top()); // TODO + driven_by_opaque_box.insert(bit); + map_file << "pi " << pis.size() - 1 << " " << bit.offset + << " " << bit.wire->name.c_str() << "\n"; + } + } else { + log_assert(!box_port); + } + } + + bool is_pi(SigBit bit, HierCursor cursor={}) + { + return pi_literal(bit, &cursor) != EMPTY_LIT; + } + + void pad_pi() + { + pis.push_back(std::make_pair(RTLIL::Sx, HierCursor{})); + lit_counter += 2; + } + + void append_box_ports(Cell *box, HierCursor &cursor, bool inputs) + { + for (auto &conn : box->connections_) { + bool is_input = box->input(conn.first); + bool is_output = box->output(conn.first); + + if (!(is_input || is_output) || (is_input && is_output)) + log_error("Ambiguous port direction on %s/%s\n", + log_id(box->type), log_id(conn.first)); + + if (is_input && inputs) { + int bitp = 0; + for (auto bit : conn.second) { + if (!bit.wire) { + bitp++; + continue; + } + + if (map_file.is_open()) { + log_assert(cursor.is_top()); + map_file << "pseudopo " << proper_pos_counter++ << " " << bitp + << " " << box->name.c_str() + << " " << conn.first.c_str() << "\n"; + } + + pos.push_back(std::make_pair(bit, cursor)); + + if (mapping_prep) + conn.second[bitp] = RTLIL::Sx; + + bitp++; + } + } else if (is_output && !inputs) { + for (auto &bit : conn.second) { + if (!bit.wire || bit.wire->port_input) + log_error("Bad connection"); + + + ensure_pi(bit, cursor); + keep_wires.insert(bit.wire); + } + } + } + } + + RTLIL::Module *holes_module; + + std::stringstream h_buffer; + static void write_be32(std::ostream &buffer, uint32_t u32) + { + typedef unsigned char uchar; + unsigned char u32_be[4] = { + (uchar) (u32 >> 24), (uchar) (u32 >> 16), (uchar) (u32 >> 8), (uchar) u32 + }; + buffer.write((char *) u32_be, sizeof(u32_be)); + } + + void prep_boxes(int pending_pos_num) + { + XAigerAnalysis analysis; + log_debug("preforming analysis on '%s'\n", log_id(top)); + analysis.analyze(top); + log_debug("analysis on '%s' done\n", log_id(top)); + + // boxes which have timing data, maybe a whitebox model + std::vector> nonopaque_boxes; + // boxes which are fully opaque + std::vector> opaque_boxes; + + log_debug("found boxes:\n"); + visit_hierarchy([&](HierCursor &cursor) { + auto &minfo = cursor.leaf_minfo(*this); + + for (auto box : minfo.found_blackboxes) { + log_debug(" - %s.%s (type %s): ", cursor.path().c_str(), + RTLIL::unescape_id(box->name).c_str(), + log_id(box->type)); + + Module *box_module = design->module(box->type), *box_derived; + + if (box_module && !box->parameters.empty()) { + // TODO: This is potentially costly even if a cached derivation exists + box_derived = design->module(box_module->derive(design, box->parameters)); + log_assert(box_derived); + } else { + box_derived = box_module; + } + + if (box_derived && box_derived->has_attribute(ID::abc9_box_id)) { + // This is an ABC9 box, we have timing data, maybe even a whitebox model + // These need to go last in the AIGER port list. + nonopaque_boxes.push_back(std::make_tuple(cursor, box, box_derived)); + log_debug("non-opaque\n"); + } else { + opaque_boxes.push_back(std::make_tuple(cursor, box, box_derived)); + log_debug("opaque\n"); + } + } + }); + + for (auto [cursor, box, def] : opaque_boxes) + append_box_ports(box, cursor, false); + + holes_module = design->addModule(NEW_ID); + std::vector holes_pis; + int boxes_ci_num = 0, boxes_co_num = 0; + + int box_seq = 0; + + std::vector boxes_order(analysis.seen.begin(), analysis.seen.end()); + std::reverse(boxes_order.begin(), boxes_order.end()); + + nonopaque_boxes.clear(); + for (auto box : boxes_order) { + HierCursor cursor; + Module *def = design->module(box->type); + nonopaque_boxes.push_back(std::make_tuple(cursor, box, def)); + } + + for (auto [cursor, box, def] : nonopaque_boxes) { + // use `def->name` not `box->type` as we want the derived type + Cell *holes_wb = holes_module->addCell(NEW_ID, def->name); + int holes_pi_idx = 0; + + if (map_file.is_open()) { + log_assert(cursor.is_top()); + map_file << "box " << box_seq << " " << box->name.c_str() << "\n"; + } + box_seq++; + + for (auto port_id : def->ports) { + Wire *port = def->wire(port_id); + log_assert(port); + + SigSpec conn = box->hasPort(port_id) ? box->getPort(port_id) : SigSpec{}; + + if (port->port_input && !port->port_output) { + // primary + for (int i = 0; i < port->width; i++) { + SigBit bit; + if (i < conn.size()) { + bit = conn[i]; + } else { + // FIXME: hierarchical path + log_warning("connection on port %s[%d] of instance %s (type %s) missing, using 1'bx\n", + log_id(port_id), i, log_id(box), log_id(box->type)); + bit = RTLIL::Sx; + } + + pos.push_back(std::make_pair(bit, cursor)); + } + boxes_co_num += port->width; + + if (mapping_prep && !conn.empty()) + box->setPort(port_id, SigSpec(RTLIL::Sx, conn.size())); + + // holes + SigSpec in_conn; + for (int i = 0; i < port->width; i++) { + while (holes_pi_idx >= (int) holes_pis.size()) { + Wire *w = holes_module->addWire(NEW_ID, 1); + w->port_input = true; + holes_module->ports.push_back(w->name); + holes_pis.push_back(w); + } + in_conn.append(holes_pis[holes_pi_idx]); + holes_pi_idx++; + } + holes_wb->setPort(port_id, in_conn); + } else if (port->port_output && !port->port_input) { + // primary + for (int i = 0; i < port->width; i++) { + SigBit bit; + if (i < conn.size() && conn[i].is_wire()) { + bit = conn[i]; + } else { + // FIXME: hierarchical path + log_warning("connection on port %s[%d] of instance %s (type %s) missing\n", + log_id(port_id), i, log_id(box), log_id(box->type)); + pad_pi(); + continue; + } + + ensure_pi(bit, cursor, true); + keep_wires.insert(bit.wire); + } + boxes_ci_num += port->width; + + // holes + Wire *w = holes_module->addWire(NEW_ID, port->width); + w->port_output = true; + holes_module->ports.push_back(w->name); + holes_wb->setPort(port_id, w); + } else { + log_error("Ambiguous port direction on %s/%s\n", + log_id(box->type), log_id(port_id)); + } + } + } + + for (auto [cursor, box, def] : opaque_boxes) + append_box_ports(box, cursor, true); + + write_be32(h_buffer, 1); + write_be32(h_buffer, pis.size()); + log_debug("ciNum = %zu\n", pis.size()); + write_be32(h_buffer, pending_pos_num + pos.size()); + log_debug("coNum = %zu\n", pending_pos_num + pos.size()); + write_be32(h_buffer, pis.size() - boxes_ci_num); + log_debug("piNum = %zu\n", pis.size() - boxes_ci_num); + write_be32(h_buffer, pending_pos_num + pos.size() - boxes_co_num); + log_debug("poNum = %zu\n", pending_pos_num + pos.size() - boxes_co_num); + write_be32(h_buffer, nonopaque_boxes.size()); + + box_seq = 0; + for (auto [cursor, box, def] : nonopaque_boxes) { + int box_ci_num = 0, box_co_num = 0; + for (auto port_id : def->ports) { + Wire *port = def->wire(port_id); + log_assert(port); + if (port->port_input && !port->port_output) { + box_co_num += port->width; + } else if (port->port_output && !port->port_input) { + box_ci_num += port->width; + } else { + log_abort(); + } + } + + write_be32(h_buffer, box_co_num); + write_be32(h_buffer, box_ci_num); + write_be32(h_buffer, def->attributes.at(ID::abc9_box_id).as_int()); + write_be32(h_buffer, box_seq++); + } + } + + void clear_boxes() + { + design->remove(holes_module); + } + + void write(std::ostream *f) { + reset_counters(); + + for (auto w : top->wires()) + if (w->port_input) + for (int i = 0; i < w->width; i++) + ensure_pi(SigBit(w, i)); + + int proper_po_num = 0; + for (auto w : top->wires()) + if (w->port_output) + proper_po_num += w->width; + + prep_boxes(proper_po_num); + for (auto w : top->wires()) + if (w->port_output) + for (int i = 0; i < w->width; i++) { + if (map_file.is_open() && !driven_by_opaque_box.count(SigBit(w, i))) { + map_file << "po " << proper_pos_counter++ << " " << i + << " " << w->name.c_str() << "\n"; + } + pos.push_back(std::make_pair(SigBit(w, i), HierCursor{})); + } + + this->f = f; + // start with the header + ninputs = pis.size(); + noutputs = pos.size(); + write_header(); + // insert padding where output literals will go (once known) + for (auto _ : pos) { + char buf[16]; + snprintf(buf, sizeof(buf) - 1, "%08d\n", 0); + f->write(buf, strlen(buf)); + } + auto data_start = f->tellp(); + + // now the guts + std::vector outlits; + for (auto &pair : pos) + outlits.push_back(eval_po(pair.first, &pair.second)); + + // revisit header and the list of outputs + f->seekp(0); + ninputs = pis.size(); + noutputs = pos.size(); + write_header(); + for (auto lit : outlits) { + char buf[16]; + snprintf(buf, sizeof(buf) - 1, "%08d\n", lit); + f->write(buf, strlen(buf)); + } + // double check we arrived at the same offset for the + // main data section + log_assert(data_start == f->tellp()); + + // extensions + f->seekp(0, std::ios::end); + + f->put('c'); + + // insert empty 'r' and 's' sections (abc crashes if we provide 'a' without those) + f->put('r'); + write_be32(*f, 4); + write_be32(*f, 0); + f->put('s'); + write_be32(*f, 4); + write_be32(*f, 0); + + f->put('h'); + // TODO: get rid of std::string copy + std::string h_buffer_str = h_buffer.str(); + write_be32(*f, h_buffer_str.size()); + f->write(h_buffer_str.data(), h_buffer_str.size()); + +#if 1 + f->put('a'); + write_be32(*f, 0); // size to be filled later + auto holes_aiger_start = f->tellp(); + { + AigerWriter holes_writer; + holes_writer.flatten = true; + holes_writer.inline_whiteboxes = true; + holes_writer.setup(holes_module); + holes_writer.write(f); + } + auto holes_aiger_size = f->tellp() - holes_aiger_start; + f->seekp(holes_aiger_start, std::ios::beg); + f->seekp(-4, std::ios::cur); + write_be32(*f, holes_aiger_size); +#endif + f->seekp(0, std::ios::end); + + if (mapping_prep) { + std::vector to_remove_cells; + for (auto cell : top->cells()) + if (!top_minfo->found_blackboxes.count(cell)) + to_remove_cells.push_back(cell); + for (auto cell : to_remove_cells) + top->remove(cell); + pool to_remove; + for (auto wire : top->wires()) + if (!wire->port_input && !wire->port_output && !keep_wires.count(wire)) + to_remove.insert(wire); + top->remove(to_remove); + } + + clear_boxes(); + } +}; + +struct Aiger2Backend : Backend { + Aiger2Backend() : Backend("aiger2", "(experimental) write design to AIGER file") + { + experimental(); + } + + void help() override + { + // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| + log("\n"); + log(" write_aiger2 [options] [filename]\n"); + log("\n"); + log("Write the selected module to an AIGER file.\n"); + log("\n"); + log(" -strash\n"); + log(" perform structural hashing while writing\n"); + log("\n"); + log(" -flatten\n"); + log(" allow descending into submodules and write a flattened view of the design\n"); + log(" hierarchy starting at the selected top\n"); + log("\n"); + log("This command is able to ingest all combinational cells except for:\n"); + log("\n"); + pool supported = {KNOWN_OPS}; + CellTypes ct; + ct.setup_internals_eval(); + log(" "); + int col = 0; + for (auto pair : ct.cell_types) + if (!supported.count(pair.first)) { + if (col + pair.first.size() + 2 > 72) { + log("\n "); + col = 0; + } + col += pair.first.size() + 2; + log("%s, ", log_id(pair.first)); + } + log("\n"); + log("\n"); + log("And all combinational gates except for:\n"); + log("\n"); + CellTypes ct2; + ct2.setup_stdcells(); + log(" "); + col = 0; + for (auto pair : ct2.cell_types) + if (!supported.count(pair.first)) { + if (col + pair.first.size() + 2 > 72) { + log("\n "); + col = 0; + } + col += pair.first.size() + 2; + log("%s, ", log_id(pair.first)); + } + log("\n"); + } + + void execute(std::ostream *&f, std::string filename, std::vector args, Design *design) override + { + log_header(design, "Executing AIGER2 backend.\n"); + + size_t argidx; + AigerWriter writer; + writer.const_folding = true; + for (argidx = 1; argidx < args.size(); argidx++) { + if (args[argidx] == "-strash") + writer.strashing = true; + else if (args[argidx] == "-flatten") + writer.flatten = true; + else + break; + } + extra_args(f, filename, args, argidx); + + Module *top = design->top_module(); + + if (!top || !design->selected_whole_module(top)) + log_cmd_error("No top module selected\n"); + + design->bufNormalize(true); + writer.setup(top); + writer.write(f); + + // we are leaving the sacred land, un-bufnormalize + // (if not, this will lead to bugs: the buf-normalized + // flag must not be kept on past the code that can work + // with it) + design->bufNormalize(false); + } +} Aiger2Backend; + +struct XAiger2Backend : Backend { + XAiger2Backend() : Backend("xaiger2", "(experimental) write module to XAIGER file") + { + experimental(); + } + + void help() override + { + // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| + log("\n"); + log(" write_xaiger2 [options] [filename]\n"); + log("\n"); + log("Write the selected module to a XAIGER file including the 'h' and 'a' extensions\n"); + log("with box information for ABC.\n"); + log("\n"); + log(" -strash\n"); + log(" perform structural hashing while writing\n"); + log("\n"); + log(" -flatten\n"); + log(" allow descending into submodules and write a flattened view of the design\n"); + log(" hierarchy starting at the selected top\n"); + log("\n"); + log(" -mapping_prep\n"); + log(" after the file is written, prepare the module for reintegration of\n"); + log(" a mapping in a subsequent command. all cells which are not blackboxed nor\n"); + log(" whiteboxed are removed from the design as well as all wires which only\n"); + log(" connect to removed cells\n"); + log(" (conflicts with -flatten)\n"); + log("\n"); + log(" -map2 \n"); + log(" write a map2 file which 'read_xaiger2 -sc_mapping' can read to\n"); + log(" reintegrate a mapping\n"); + log(" (conflicts with -flatten)\n"); + log("\n"); + } + + void execute(std::ostream *&f, std::string filename, std::vector args, Design *design) override + { + log_header(design, "Executing XAIGER2 backend.\n"); + + size_t argidx; + XAigerWriter writer; + std::string map_filename; + writer.const_folding = true; + for (argidx = 1; argidx < args.size(); argidx++) { + if (args[argidx] == "-strash") + writer.strashing = true; + else if (args[argidx] == "-flatten") + writer.flatten = true; + else if (args[argidx] == "-mapping_prep") + writer.mapping_prep = true; + else if (args[argidx] == "-map2" && argidx + 1 < args.size()) + map_filename = args[++argidx]; + else + break; + } + extra_args(f, filename, args, argidx); + + Module *top = design->top_module(); + + if (!top || !design->selected_whole_module(top)) + log_cmd_error("No top module selected\n"); + + if (!map_filename.empty()) { + writer.map_file.open(map_filename); + if (!writer.map_file) + log_cmd_error("Failed to open '%s' for writing\n", map_filename.c_str()); + } + + design->bufNormalize(true); + writer.setup(top); + writer.write(f); + + // we are leaving the sacred land, un-bufnormalize + // (if not, this will lead to bugs: the buf-normalized + // flag must not be kept on past the code that can work + // with it) + design->bufNormalize(false); + } +} XAiger2Backend; + +PRIVATE_NAMESPACE_END diff --git a/backends/blif/blif.cc b/backends/blif/blif.cc index 788b7f951..5a5b9219f 100644 --- a/backends/blif/blif.cc +++ b/backends/blif/blif.cc @@ -387,7 +387,7 @@ struct BlifDumper auto &inputs = cell->getPort(ID::A); auto width = cell->parameters.at(ID::WIDTH).as_int(); auto depth = cell->parameters.at(ID::DEPTH).as_int(); - vector table = cell->parameters.at(ID::TABLE).bits; + vector table = cell->parameters.at(ID::TABLE).to_bits(); while (GetSize(table) < 2*width*depth) table.push_back(State::S0); log_assert(inputs.size() == width); @@ -649,7 +649,7 @@ struct BlifBackend : public Backend { if (module->get_bool_attribute(ID::top)) top_module_name = module->name.str(); - *f << stringf("# Generated by %s\n", yosys_version_str); + *f << stringf("# Generated by %s\n", yosys_maybe_version()); std::vector mod_list; diff --git a/backends/btor/btor.cc b/backends/btor/btor.cc index 9cfd967e5..bfd293557 100644 --- a/backends/btor/btor.cc +++ b/backends/btor/btor.cc @@ -30,6 +30,7 @@ #include "kernel/mem.h" #include "kernel/json.h" #include "kernel/yw.h" +#include "kernel/utils.h" #include USING_YOSYS_NAMESPACE @@ -711,9 +712,9 @@ struct BtorWorker Const initval; for (int i = 0; i < GetSize(sig_q); i++) if (initbits.count(sig_q[i])) - initval.bits.push_back(initbits.at(sig_q[i]) ? State::S1 : State::S0); + initval.bits().push_back(initbits.at(sig_q[i]) ? State::S1 : State::S0); else - initval.bits.push_back(State::Sx); + initval.bits().push_back(State::Sx); int nid_init_val = -1; @@ -832,7 +833,10 @@ struct BtorWorker } } - if (constword) + // If not fully defined, undef bits should be able to take a + // different value for each address so we can't initialise from + // one value (and btor2parser doesn't like it) + if (constword && firstword.is_fully_def()) { if (verbose) btorf("; initval = %s\n", log_signal(firstword)); @@ -1042,7 +1046,7 @@ struct BtorWorker Const c(bit.data); while (i+GetSize(c) < GetSize(sig) && sig[i+GetSize(c)].wire == nullptr) - c.bits.push_back(sig[i+GetSize(c)].data); + c.bits().push_back(sig[i+GetSize(c)].data); if (consts.count(c) == 0) { int sid = get_bv_sid(GetSize(c)); @@ -1077,6 +1081,7 @@ struct BtorWorker btorf("%d input %d\n", nid, sid); ywmap_input(s); nid_width[nid] = GetSize(s); + add_nid_sig(nid, s); for (int j = 0; j < GetSize(s); j++) nidbits.push_back(make_pair(nid, j)); @@ -1494,7 +1499,7 @@ struct BtorWorker { ywmap_json.begin_object(); ywmap_json.entry("version", "Yosys Witness BTOR map"); - ywmap_json.entry("generator", yosys_version_str); + ywmap_json.entry("generator", yosys_maybe_version()); ywmap_json.name("clocks"); ywmap_json.begin_array(); @@ -1608,7 +1613,7 @@ struct BtorBackend : public Backend { log_cmd_error("No top module found.\n"); *f << stringf("; BTOR description generated by %s for module %s.\n", - yosys_version_str, log_id(topmod)); + yosys_maybe_version(), log_id(topmod)); BtorWorker(*f, topmod, verbose, single_bad, cover_mode, print_internal_names, info_filename, ywmap_filename); diff --git a/backends/btor/test_cells.sh b/backends/btor/test_cells.sh index f8bd79782..fc7f5b75c 100755 --- a/backends/btor/test_cells.sh +++ b/backends/btor/test_cells.sh @@ -10,11 +10,11 @@ cd test_cells.tmp for fn in test_*.il; do ../../../yosys -p " - read_ilang $fn + read_rtlil $fn rename gold gate synth - read_ilang $fn + read_rtlil $fn miter -equiv -make_assert -flatten gold gate main hierarchy -top main write_btor ${fn%.il}.btor diff --git a/backends/cxxrtl/cxxrtl_backend.cc b/backends/cxxrtl/cxxrtl_backend.cc index 8dc14863d..7080f54d5 100644 --- a/backends/cxxrtl/cxxrtl_backend.cc +++ b/backends/cxxrtl/cxxrtl_backend.cc @@ -47,7 +47,7 @@ struct Scheduler { struct Vertex { T *data; Vertex *prev, *next; - pool preds, succs; + pool preds, succs; Vertex() : data(NULL), prev(this), next(this) {} Vertex(T *data) : data(data), prev(NULL), next(NULL) {} @@ -200,7 +200,7 @@ bool is_extending_cell(RTLIL::IdString type) bool is_inlinable_cell(RTLIL::IdString type) { return is_unary_cell(type) || is_binary_cell(type) || type.in( - ID($mux), ID($concat), ID($slice), ID($pmux), ID($bmux), ID($demux)); + ID($mux), ID($concat), ID($slice), ID($pmux), ID($bmux), ID($demux), ID($bwmux)); } bool is_ff_cell(RTLIL::IdString type) @@ -300,10 +300,10 @@ struct FlowGraph { }; std::vector nodes; - dict> wire_comb_defs, wire_sync_defs, wire_uses; - dict, hash_ptr_ops> node_comb_defs, node_sync_defs, node_uses; + dict> wire_comb_defs, wire_sync_defs, wire_uses; + dict> node_comb_defs, node_sync_defs, node_uses; dict wire_def_inlinable; - dict> wire_use_inlinable; + dict> wire_use_inlinable; dict bit_has_state; ~FlowGraph() @@ -328,7 +328,7 @@ struct FlowGraph { node_comb_defs[node].insert(chunk.wire); } } - for (auto bit : sig.bits()) + for (auto bit : sig) bit_has_state[bit] |= is_ff; // Only comb defs of an entire wire in the right order can be inlined. if (!is_ff && sig.is_wire()) { @@ -365,7 +365,7 @@ struct FlowGraph { return false; } - bool is_inlinable(const RTLIL::Wire *wire, const pool &nodes) const + bool is_inlinable(const RTLIL::Wire *wire, const pool &nodes) const { // Can the wire be inlined, knowing that the given nodes are reachable? if (nodes.size() != 1) @@ -612,11 +612,11 @@ std::string escape_c_string(const std::string &input) output.push_back('"'); for (auto c : input) { if (::isprint(c)) { - if (c == '\\') + if (c == '\\' || c == '"') output.push_back('\\'); output.push_back(c); } else { - char l = c & 0x3, m = (c >> 3) & 0x3, h = (c >> 6) & 0x3; + char l = c & 0x7, m = (c >> 3) & 0x7, h = (c >> 6) & 0x3; output.append("\\"); output.push_back('0' + h); output.push_back('0' + m); @@ -864,7 +864,7 @@ struct CxxrtlWorker { if (!module->has_attribute(ID(cxxrtl_template))) return {}; - if (module->attributes.at(ID(cxxrtl_template)).flags != RTLIL::CONST_FLAG_STRING) + if (!(module->attributes.at(ID(cxxrtl_template)).flags & RTLIL::CONST_FLAG_STRING)) log_cmd_error("Attribute `cxxrtl_template' of module `%s' is not a string.\n", log_id(module)); std::vector param_names = split_by(module->get_string_attribute(ID(cxxrtl_template)), " \t"); @@ -1198,6 +1198,14 @@ struct CxxrtlWorker { f << ">("; dump_sigspec_rhs(cell->getPort(ID::S), for_debug); f << ").val()"; + // Bitwise muxes + } else if (cell->type == ID($bwmux)) { + dump_sigspec_rhs(cell->getPort(ID::A), for_debug); + f << ".bwmux("; + dump_sigspec_rhs(cell->getPort(ID::B), for_debug); + f << ","; + dump_sigspec_rhs(cell->getPort(ID::S), for_debug); + f << ").val()"; // Demuxes } else if (cell->type == ID($demux)) { dump_sigspec_rhs(cell->getPort(ID::A), for_debug); @@ -1665,15 +1673,15 @@ struct CxxrtlWorker { switch (bit) { case RTLIL::S0: case RTLIL::S1: - compare_mask.bits.push_back(RTLIL::S1); - compare_value.bits.push_back(bit); + compare_mask.bits().push_back(RTLIL::S1); + compare_value.bits().push_back(bit); break; case RTLIL::Sx: case RTLIL::Sz: case RTLIL::Sa: - compare_mask.bits.push_back(RTLIL::S0); - compare_value.bits.push_back(RTLIL::S0); + compare_mask.bits().push_back(RTLIL::S0); + compare_value.bits().push_back(RTLIL::S0); break; default: @@ -2402,7 +2410,12 @@ struct CxxrtlWorker { auto cell_attrs = scopeinfo_attributes(cell, ScopeinfoAttrs::Cell); cell_attrs.erase(ID::module_not_derived); f << indent << "scopes->add(path, " << escape_cxx_string(get_hdl_name(cell)) << ", "; - f << escape_cxx_string(cell->get_string_attribute(ID(module))) << ", "; + if (module_attrs.count(ID(hdlname))) { + f << escape_cxx_string(module_attrs.at(ID(hdlname)).decode_string()); + } else { + f << escape_cxx_string(cell->get_string_attribute(ID(module))); + } + f << ", "; dump_serialized_metadata(module_attrs); f << ", "; dump_serialized_metadata(cell_attrs); @@ -2416,8 +2429,6 @@ struct CxxrtlWorker { inc_indent(); for (auto wire : module->wires()) { const auto &debug_wire_type = debug_wire_types[wire]; - if (!wire->name.isPublic()) - continue; count_public_wires++; switch (debug_wire_type.type) { case WireType::BUFFERED: @@ -2425,6 +2436,9 @@ struct CxxrtlWorker { // Member wire std::vector flags; + if (!wire->name.isPublic()) + flags.push_back("GENERATED"); + if (wire->port_input && wire->port_output) flags.push_back("INOUT"); else if (wire->port_output) @@ -2497,7 +2511,7 @@ struct CxxrtlWorker { // Alias of a member wire const RTLIL::Wire *aliasee = debug_wire_type.sig_subst.as_wire(); f << indent << "items->add(path, " << escape_cxx_string(get_hdl_name(wire)) << ", "; - dump_debug_attrs(aliasee); + dump_debug_attrs(wire); f << ", "; // If the aliasee is an outline, then the alias must be an outline, too; otherwise downstream // tooling has no way to find out about the outline. @@ -3028,7 +3042,7 @@ struct CxxrtlWorker { if (init == RTLIL::Const()) { init = RTLIL::Const(State::Sx, GetSize(bit.wire)); } - init[bit.offset] = port.init_value[i]; + init.bits()[bit.offset] = port.init_value[i]; } } } @@ -3080,7 +3094,7 @@ struct CxxrtlWorker { // without feedback arcs can generally be evaluated in a single pass, i.e. it always requires only // a single delta cycle. Scheduler scheduler; - dict::Vertex*, hash_ptr_ops> node_vertex_map; + dict::Vertex*> node_vertex_map; for (auto node : flow.nodes) node_vertex_map[node] = scheduler.add(node); for (auto node_comb_def : flow.node_comb_defs) { @@ -3095,7 +3109,7 @@ struct CxxrtlWorker { // Find out whether the order includes any feedback arcs. std::vector node_order; - pool evaluated_nodes; + pool evaluated_nodes; pool feedback_wires; for (auto vertex : scheduler.schedule()) { auto node = vertex->data; @@ -3139,7 +3153,7 @@ struct CxxrtlWorker { } // Discover nodes reachable from primary outputs (i.e. members) and collect reachable wire users. - pool worklist; + pool worklist; for (auto node : flow.nodes) { if (node->type == FlowGraph::Node::Type::CELL_EVAL && !is_internal_cell(node->cell->type)) worklist.insert(node); // node evaluates a submodule @@ -3159,8 +3173,8 @@ struct CxxrtlWorker { worklist.insert(node); // node drives public wires } } - dict> live_wires; - pool live_nodes; + dict> live_wires; + pool live_nodes; while (!worklist.empty()) { auto node = worklist.pop(); live_nodes.insert(node); @@ -3290,15 +3304,15 @@ struct CxxrtlWorker { // Discover nodes reachable from primary outputs (i.e. outlines) up until primary inputs (i.e. members) // and collect reachable wire users. - pool worklist; + pool worklist; for (auto node : flow.nodes) { if (flow.node_comb_defs.count(node)) for (auto wire : flow.node_comb_defs[node]) if (debug_wire_types[wire].is_outline()) worklist.insert(node); // node drives outline } - dict> debug_live_wires; - pool debug_live_nodes; + dict> debug_live_wires; + pool debug_live_nodes; while (!worklist.empty()) { auto node = worklist.pop(); debug_live_nodes.insert(node); diff --git a/backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi.h b/backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi.h index ae42733ad..62ca38943 100644 --- a/backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi.h +++ b/backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi.h @@ -200,6 +200,10 @@ enum cxxrtl_flag { // node, such as inputs and dangling wires. CXXRTL_UNDRIVEN = 1 << 4, + // Generated correspond to netlist nodes that correspond to state with an internal name, that + // need to be saved, but wouldn't otherwise have a debug item generated. + CXXRTL_GENERATED = 1 << 5, + // More object flags may be added in the future, but the existing ones will never change. }; diff --git a/backends/cxxrtl/runtime/cxxrtl/cxxrtl.h b/backends/cxxrtl/runtime/cxxrtl/cxxrtl.h index d1d6bd8dc..fbbe2373f 100644 --- a/backends/cxxrtl/runtime/cxxrtl/cxxrtl.h +++ b/backends/cxxrtl/runtime/cxxrtl/cxxrtl.h @@ -498,6 +498,11 @@ struct value : public expr_base> { return result; } + CXXRTL_ALWAYS_INLINE + value bwmux(const value &b, const value &s) const { + return (bit_and(s.bit_not())).bit_or(b.bit_and(s)); + } + template value demux(const value &sel) const { static_assert(Bits << SelBits == ResultBits, "invalid sizes used in demux()"); @@ -1127,7 +1132,7 @@ struct fmt_part { } case UNICHAR: { - uint32_t codepoint = val.template get(); + uint32_t codepoint = val.template zcast<32>().template get(); if (codepoint >= 0x10000) buf += (char)(0xf0 | (codepoint >> 18)); else if (codepoint >= 0x800) @@ -1289,6 +1294,7 @@ struct debug_item : ::cxxrtl_object { DRIVEN_SYNC = CXXRTL_DRIVEN_SYNC, DRIVEN_COMB = CXXRTL_DRIVEN_COMB, UNDRIVEN = CXXRTL_UNDRIVEN, + GENERATED = CXXRTL_GENERATED, }; debug_item(const ::cxxrtl_object &object) : cxxrtl_object(object) {} @@ -1764,7 +1770,7 @@ value shr_uu(const value &a, const value &b) { template CXXRTL_ALWAYS_INLINE value shr_su(const value &a, const value &b) { - return a.shr(b).template scast(); + return a.template scast().shr(b); } template @@ -2005,7 +2011,7 @@ std::pair, value> divmod_uu(const value &a, const val value quotient; value remainder; value dividend = a.template zext(); - value divisor = b.template zext(); + value divisor = b.template trunc().template zext(); std::tie(quotient, remainder) = dividend.udivmod(divisor); return {quotient.template trunc(), remainder.template trunc()}; } diff --git a/backends/cxxrtl/runtime/cxxrtl/cxxrtl_vcd.h b/backends/cxxrtl/runtime/cxxrtl/cxxrtl_vcd.h index cb2ccf5fc..e8be70028 100644 --- a/backends/cxxrtl/runtime/cxxrtl/cxxrtl_vcd.h +++ b/backends/cxxrtl/runtime/cxxrtl/cxxrtl_vcd.h @@ -50,9 +50,13 @@ class vcd_writer { void emit_scope(const std::vector &scope) { assert(!streaming); - while (current_scope.size() > scope.size() || - (current_scope.size() > 0 && - current_scope[current_scope.size() - 1] != scope[current_scope.size() - 1])) { + size_t same_scope_count = 0; + while ((same_scope_count < current_scope.size()) && + (same_scope_count < scope.size()) && + (current_scope[same_scope_count] == scope[same_scope_count])) { + same_scope_count++; + } + while (current_scope.size() > same_scope_count) { buffer += "$upscope $end\n"; current_scope.pop_back(); } @@ -123,6 +127,8 @@ class vcd_writer { bool bit_curr = var.curr[bit / (8 * sizeof(chunk_t))] & (1 << (bit % (8 * sizeof(chunk_t)))); buffer += (bit_curr ? '1' : '0'); } + if (var.width == 0) + buffer += '0'; buffer += ' '; emit_ident(var.ident); buffer += '\n'; diff --git a/backends/edif/edif.cc b/backends/edif/edif.cc index 553eb23d6..581590287 100644 --- a/backends/edif/edif.cc +++ b/backends/edif/edif.cc @@ -231,7 +231,8 @@ struct EdifBackend : public Backend { *f << stringf(" (edifVersion 2 0 0)\n"); *f << stringf(" (edifLevel 0)\n"); *f << stringf(" (keywordMap (keywordLevel 0))\n"); - *f << stringf(" (comment \"Generated by %s\")\n", yosys_version_str); + + *f << stringf(" (comment \"Generated by %s\")\n", yosys_maybe_version()); *f << stringf(" (external LIB\n"); *f << stringf(" (edifLevel 0)\n"); @@ -334,20 +335,20 @@ struct EdifBackend : public Backend { auto add_prop = [&](IdString name, Const val) { if ((val.flags & RTLIL::CONST_FLAG_STRING) != 0) *f << stringf("\n (property %s (string \"%s\"))", EDIF_DEF(name), val.decode_string().c_str()); - else if (val.bits.size() <= 32 && RTLIL::SigSpec(val).is_fully_def()) + else if (val.size() <= 32 && RTLIL::SigSpec(val).is_fully_def()) *f << stringf("\n (property %s (integer %u))", EDIF_DEF(name), val.as_int()); else { std::string hex_string = ""; - for (size_t i = 0; i < val.bits.size(); i += 4) { + for (auto i = 0; i < val.size(); i += 4) { int digit_value = 0; - if (i+0 < val.bits.size() && val.bits.at(i+0) == RTLIL::State::S1) digit_value |= 1; - if (i+1 < val.bits.size() && val.bits.at(i+1) == RTLIL::State::S1) digit_value |= 2; - if (i+2 < val.bits.size() && val.bits.at(i+2) == RTLIL::State::S1) digit_value |= 4; - if (i+3 < val.bits.size() && val.bits.at(i+3) == RTLIL::State::S1) digit_value |= 8; + if (i+0 < val.size() && val.at(i+0) == RTLIL::State::S1) digit_value |= 1; + if (i+1 < val.size() && val.at(i+1) == RTLIL::State::S1) digit_value |= 2; + if (i+2 < val.size() && val.at(i+2) == RTLIL::State::S1) digit_value |= 4; + if (i+3 < val.size() && val.at(i+3) == RTLIL::State::S1) digit_value |= 8; char digit_str[2] = { "0123456789abcdef"[digit_value], 0 }; hex_string = std::string(digit_str) + hex_string; } - *f << stringf("\n (property %s (string \"%d'h%s\"))", EDIF_DEF(name), GetSize(val.bits), hex_string.c_str()); + *f << stringf("\n (property %s (string \"%d'h%s\"))", EDIF_DEF(name), GetSize(val), hex_string.c_str()); } }; for (auto module : sorted_modules) diff --git a/backends/firrtl/firrtl.cc b/backends/firrtl/firrtl.cc index dc76dbeec..e4254f85a 100644 --- a/backends/firrtl/firrtl.cc +++ b/backends/firrtl/firrtl.cc @@ -149,7 +149,7 @@ std::string dump_const(const RTLIL::Const &data) // Numeric (non-real) parameter. else { - int width = data.bits.size(); + int width = data.size(); // If a standard 32-bit int, then emit standard int value like "56" or // "-56". Firrtl supports negative-valued int literals. @@ -163,7 +163,7 @@ std::string dump_const(const RTLIL::Const &data) for (int i = 0; i < width; i++) { - switch (data.bits[i]) + switch (data[i]) { case State::S0: break; case State::S1: int_val |= (1 << i); break; @@ -205,7 +205,7 @@ std::string dump_const(const RTLIL::Const &data) for (int i = width - 1; i >= 0; i--) { log_assert(i < width); - switch (data.bits[i]) + switch (data[i]) { case State::S0: res_str += "0"; break; case State::S1: res_str += "1"; break; @@ -1215,9 +1215,6 @@ struct FirrtlBackend : public Backend { } extra_args(f, filename, args, argidx); - if (!design->full_selection()) - log_cmd_error("This command only operates on fully selected designs!\n"); - log_header(design, "Executing FIRRTL backend.\n"); log_push(); @@ -1226,11 +1223,12 @@ struct FirrtlBackend : public Backend { Pass::call(design, "demuxmap"); Pass::call(design, "bwmuxmap"); + used_names.clear(); namecache.clear(); autoid_counter = 0; // Get the top module, or a reasonable facsimile - we need something for the circuit name. - Module *top = design->top_module(); + Module *top = nullptr; Module *last = nullptr; // Generate module and wire names. for (auto module : design->modules()) { @@ -1265,6 +1263,7 @@ struct FirrtlBackend : public Backend { } } + used_names.clear(); namecache.clear(); autoid_counter = 0; } diff --git a/backends/functional/cxx.cc b/backends/functional/cxx.cc index b8b25df8b..1f677120a 100644 --- a/backends/functional/cxx.cc +++ b/backends/functional/cxx.cc @@ -246,6 +246,8 @@ struct FunctionalCxxBackend : public Backend { // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| log("\n"); + log("TODO: add help message\n"); + log("\n"); } void printCxx(std::ostream &stream, std::string, Module *module) diff --git a/backends/functional/smtlib_rosette.cc b/backends/functional/smtlib_rosette.cc index ea14da854..c9e737d19 100644 --- a/backends/functional/smtlib_rosette.cc +++ b/backends/functional/smtlib_rosette.cc @@ -210,14 +210,8 @@ struct SmtrModule { state_struct.insert(state->name, state->sort); } - void write(std::ostream &out) - { - SExprWriter w(out); - - input_struct.write_definition(w); - output_struct.write_definition(w); - state_struct.write_definition(w); - + void write_eval(SExprWriter &w) + { w.push(); w.open(list("define", list(name, "inputs", "state"))); auto inlined = [&](Functional::Node n) { @@ -240,7 +234,10 @@ struct SmtrModule { output_struct.write_value(w, [&](IdString name) { return node_to_sexpr(ir.output(name).value()); }); state_struct.write_value(w, [&](IdString name) { return node_to_sexpr(ir.state(name).next_value()); }); w.pop(); + } + void write_initial(SExprWriter &w) + { w.push(); auto initial = name + "_initial"; w.open(list("define", initial)); @@ -259,6 +256,18 @@ struct SmtrModule { } w.pop(); } + + void write(std::ostream &out) + { + SExprWriter w(out); + + input_struct.write_definition(w); + output_struct.write_definition(w); + state_struct.write_definition(w); + + write_eval(w); + write_initial(w); + } }; struct FunctionalSmtrBackend : public Backend { @@ -267,7 +276,7 @@ struct FunctionalSmtrBackend : public Backend { void help() override { // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| log("\n"); - log(" write_functional_rosette [options] [selection] [filename]\n"); + log(" write_functional_rosette [options] [filename]\n"); log("\n"); log("Functional Rosette Backend.\n"); log("\n"); diff --git a/backends/functional/test_generic.cc b/backends/functional/test_generic.cc index 10a7a50f0..a9dfd0c70 100644 --- a/backends/functional/test_generic.cc +++ b/backends/functional/test_generic.cc @@ -105,7 +105,7 @@ struct MemContentsTest { RTLIL::Const values; for(addr_t addr = low; addr <= high; addr++) { RTLIL::Const word(data_dist(rnd), data_width); - values.bits.insert(values.bits.end(), word.bits.begin(), word.bits.end()); + values.bits().insert(values.bits().end(), word.begin(), word.end()); } insert_concatenated(low, values); } @@ -122,6 +122,8 @@ struct FunctionalTestGeneric : public Pass { // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| log("\n"); + log("TODO: add help message\n"); + log("\n"); } void execute(std::vector args, RTLIL::Design *design) override diff --git a/backends/intersynth/intersynth.cc b/backends/intersynth/intersynth.cc index 59173c4a2..dcf107de3 100644 --- a/backends/intersynth/intersynth.cc +++ b/backends/intersynth/intersynth.cc @@ -176,11 +176,11 @@ struct IntersynthBackend : public Backend { } } for (auto ¶m : cell->parameters) { - celltype_code += stringf(" cfg:%d %s", int(param.second.bits.size()), log_id(param.first)); - if (param.second.bits.size() != 32) { + celltype_code += stringf(" cfg:%d %s", int(param.second.size()), log_id(param.first)); + if (param.second.size() != 32) { node_code += stringf(" %s '", log_id(param.first)); - for (int i = param.second.bits.size()-1; i >= 0; i--) - node_code += param.second.bits[i] == State::S1 ? "1" : "0"; + for (int i = param.second.size()-1; i >= 0; i--) + node_code += param.second[i] == State::S1 ? "1" : "0"; } else node_code += stringf(" %s 0x%x", log_id(param.first), param.second.as_int()); } diff --git a/backends/jny/jny.cc b/backends/jny/jny.cc index 1c163dba5..4aacb4e20 100644 --- a/backends/jny/jny.cc +++ b/backends/jny/jny.cc @@ -125,7 +125,7 @@ struct JnyWriter f << "{\n"; f << " \"$schema\": \"https://raw.githubusercontent.com/YosysHQ/yosys/main/misc/jny.schema.json\",\n"; - f << stringf(" \"generator\": \"%s\",\n", escape_string(yosys_version_str).c_str()); + f << stringf(" \"generator\": \"%s\",\n", escape_string(yosys_maybe_version()).c_str()); f << " \"version\": \"0.0.1\",\n"; f << " \"invocation\": \"" << escape_string(invk) << "\",\n"; f << " \"features\": ["; diff --git a/backends/json/json.cc b/backends/json/json.cc index 2f442c494..98e929dfa 100644 --- a/backends/json/json.cc +++ b/backends/json/json.cc @@ -34,6 +34,7 @@ struct JsonWriter bool use_selection; bool aig_mode; bool compat_int_mode; + bool scopeinfo_mode; Design *design; Module *module; @@ -43,9 +44,9 @@ struct JsonWriter dict sigids; pool aig_models; - JsonWriter(std::ostream &f, bool use_selection, bool aig_mode, bool compat_int_mode) : + JsonWriter(std::ostream &f, bool use_selection, bool aig_mode, bool compat_int_mode, bool scopeinfo_mode) : f(f), use_selection(use_selection), aig_mode(aig_mode), - compat_int_mode(compat_int_mode) { } + compat_int_mode(compat_int_mode), scopeinfo_mode(scopeinfo_mode) { } string get_string(string str) { @@ -192,9 +193,7 @@ struct JsonWriter for (auto c : module->cells()) { if (use_selection && !module->selected(c)) continue; - // Eventually we will want to emit $scopeinfo, but currently this - // will break JSON netlist consumers like nextpnr - if (c->type == ID($scopeinfo)) + if (!scopeinfo_mode && c->type == ID($scopeinfo)) continue; f << stringf("%s\n", first ? "" : ","); f << stringf(" %s: {\n", get_name(c->name).c_str()); @@ -292,7 +291,7 @@ struct JsonWriter design->sort(); f << stringf("{\n"); - f << stringf(" \"creator\": %s,\n", get_string(yosys_version_str).c_str()); + f << stringf(" \"creator\": %s,\n", get_string(yosys_maybe_version()).c_str()); f << stringf(" \"modules\": {\n"); vector modules = use_selection ? design->selected_modules() : design->modules(); bool first_module = true; @@ -353,6 +352,12 @@ struct JsonBackend : public Backend { log(" emit 32-bit or smaller fully-defined parameter values directly\n"); log(" as JSON numbers (for compatibility with old parsers)\n"); log("\n"); + log(" -selected\n"); + log(" output only select module\n"); + log("\n"); + log(" -noscopeinfo\n"); + log(" don't include $scopeinfo cells in the output\n"); + log("\n"); log("\n"); log("The general syntax of the JSON output created by this command is as follows:\n"); log("\n"); @@ -403,7 +408,7 @@ struct JsonBackend : public Backend { log("\n"); log("The \"offset\" and \"upto\" fields are skipped if their value would be 0.\n"); log("They don't affect connection semantics, and are only used to preserve original\n"); - log("HDL bit indexing."); + log("HDL bit indexing.\n"); log("And is:\n"); log("\n"); log(" {\n"); @@ -597,6 +602,8 @@ struct JsonBackend : public Backend { { bool aig_mode = false; bool compat_int_mode = false; + bool use_selection = false; + bool scopeinfo_mode = true; size_t argidx; for (argidx = 1; argidx < args.size(); argidx++) @@ -609,13 +616,21 @@ struct JsonBackend : public Backend { compat_int_mode = true; continue; } + if (args[argidx] == "-selected") { + use_selection = true; + continue; + } + if (args[argidx] == "-noscopeinfo") { + scopeinfo_mode = false; + continue; + } break; } extra_args(f, filename, args, argidx); log_header(design, "Executing JSON backend.\n"); - JsonWriter json_writer(*f, false, aig_mode, compat_int_mode); + JsonWriter json_writer(*f, use_selection, aig_mode, compat_int_mode, scopeinfo_mode); json_writer.write_design(design); } } JsonBackend; @@ -640,6 +655,9 @@ struct JsonPass : public Pass { log(" emit 32-bit or smaller fully-defined parameter values directly\n"); log(" as JSON numbers (for compatibility with old parsers)\n"); log("\n"); + log(" -noscopeinfo\n"); + log(" don't include $scopeinfo cells in the output\n"); + log("\n"); log("See 'help write_json' for a description of the JSON format used.\n"); log("\n"); } @@ -648,6 +666,7 @@ struct JsonPass : public Pass { std::string filename; bool aig_mode = false; bool compat_int_mode = false; + bool scopeinfo_mode = true; size_t argidx; for (argidx = 1; argidx < args.size(); argidx++) @@ -664,6 +683,10 @@ struct JsonPass : public Pass { compat_int_mode = true; continue; } + if (args[argidx] == "-noscopeinfo") { + scopeinfo_mode = false; + continue; + } break; } extra_args(args, argidx, design); @@ -685,7 +708,7 @@ struct JsonPass : public Pass { f = &buf; } - JsonWriter json_writer(*f, true, aig_mode, compat_int_mode); + JsonWriter json_writer(*f, true, aig_mode, compat_int_mode, scopeinfo_mode); json_writer.write_design(design); if (!empty) { diff --git a/backends/rtlil/rtlil_backend.cc b/backends/rtlil/rtlil_backend.cc index 032954d8c..adde37356 100644 --- a/backends/rtlil/rtlil_backend.cc +++ b/backends/rtlil/rtlil_backend.cc @@ -33,13 +33,13 @@ YOSYS_NAMESPACE_BEGIN void RTLIL_BACKEND::dump_const(std::ostream &f, const RTLIL::Const &data, int width, int offset, bool autoint) { if (width < 0) - width = data.bits.size() - offset; - if ((data.flags & RTLIL::CONST_FLAG_STRING) == 0 || width != (int)data.bits.size()) { + width = data.size() - offset; + if ((data.flags & RTLIL::CONST_FLAG_STRING) == 0 || width != (int)data.size()) { if (width == 32 && autoint) { int32_t val = 0; for (int i = 0; i < width; i++) { - log_assert(offset+i < (int)data.bits.size()); - switch (data.bits[offset+i]) { + log_assert(offset+i < (int)data.size()); + switch (data[offset+i]) { case State::S0: break; case State::S1: val |= 1 << i; break; default: val = -1; break; @@ -58,8 +58,8 @@ void RTLIL_BACKEND::dump_const(std::ostream &f, const RTLIL::Const &data, int wi f << "x"; } else { for (int i = offset+width-1; i >= offset; i--) { - log_assert(i < (int)data.bits.size()); - switch (data.bits[i]) { + log_assert(i < (int)data.size()); + switch (data[i]) { case State::S0: f << stringf("0"); break; case State::S1: f << stringf("1"); break; case RTLIL::Sx: f << stringf("x"); break; @@ -125,6 +125,10 @@ void RTLIL_BACKEND::dump_wire(std::ostream &f, std::string indent, const RTLIL:: dump_const(f, it.second); f << stringf("\n"); } + if (wire->driverCell_) { + f << stringf("%s" "# driver %s %s\n", indent.c_str(), + wire->driverCell()->name.c_str(), wire->driverPort().c_str()); + } f << stringf("%s" "wire ", indent.c_str()); if (wire->width != 1) f << stringf("width %d ", wire->width); @@ -300,8 +304,8 @@ void RTLIL_BACKEND::dump_conn(std::ostream &f, std::string indent, const RTLIL:: void RTLIL_BACKEND::dump_module(std::ostream &f, std::string indent, RTLIL::Module *module, RTLIL::Design *design, bool only_selected, bool flag_m, bool flag_n) { - bool print_header = flag_m || design->selected_whole_module(module->name); - bool print_body = !flag_n || !design->selected_whole_module(module->name); + bool print_header = flag_m || module->is_selected_whole(); + bool print_body = !flag_n || !module->is_selected_whole(); if (print_header) { @@ -455,26 +459,12 @@ struct RTLILBackend : public Backend { design->sort(); log("Output filename: %s\n", filename.c_str()); - *f << stringf("# Generated by %s\n", yosys_version_str); + + *f << stringf("# Generated by %s\n", yosys_maybe_version()); RTLIL_BACKEND::dump_design(*f, design, selected, true, false); } } RTLILBackend; -struct IlangBackend : public Backend { - IlangBackend() : Backend("ilang", "(deprecated) alias of write_rtlil") { } - void help() override - { - // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| - log("\n"); - log("See `help write_rtlil`.\n"); - log("\n"); - } - void execute(std::ostream *&f, std::string filename, std::vector args, RTLIL::Design *design) override - { - RTLILBackend.execute(f, filename, args, design); - } -} IlangBackend; - struct DumpPass : public Pass { DumpPass() : Pass("dump", "print parts of the design in RTLIL format") { } void help() override diff --git a/backends/simplec/simplec.cc b/backends/simplec/simplec.cc index e283dcf7c..e70c62a71 100644 --- a/backends/simplec/simplec.cc +++ b/backends/simplec/simplec.cc @@ -657,7 +657,7 @@ struct SimplecWorker { SigSpec sig = sigmaps.at(module)(w); Const val = w->attributes.at(ID::init); - val.bits.resize(GetSize(sig), State::Sx); + val.bits().resize(GetSize(sig), State::Sx); for (int i = 0; i < GetSize(sig); i++) if (val[i] == State::S0 || val[i] == State::S1) { diff --git a/backends/smt2/smt2.cc b/backends/smt2/smt2.cc index c702d5e7e..87f5a08c8 100644 --- a/backends/smt2/smt2.cc +++ b/backends/smt2/smt2.cc @@ -24,6 +24,7 @@ #include "kernel/log.h" #include "kernel/mem.h" #include "libs/json11/json11.hpp" +#include "kernel/utils.h" #include USING_YOSYS_NAMESPACE @@ -329,13 +330,14 @@ struct Smt2Worker { sigmap.apply(bit); + if (bit_driver.count(bit)) { + export_cell(bit_driver.at(bit)); + sigmap.apply(bit); + } + if (bit.wire == nullptr) return bit == RTLIL::State::S1 ? "true" : "false"; - if (bit_driver.count(bit)) - export_cell(bit_driver.at(bit)); - sigmap.apply(bit); - if (fcache.count(bit) == 0) { if (verbose) log("%*s-> external bool: %s\n", 2+2*GetSize(recursive_cells), "", log_signal(bit)); @@ -1077,14 +1079,14 @@ struct Smt2Worker RTLIL::SigSpec sig = sigmap(wire); Const val = wire->attributes.at(ID::init); - val.bits.resize(GetSize(sig), State::Sx); + val.bits().resize(GetSize(sig), State::Sx); if (bvmode && GetSize(sig) > 1) { Const mask(State::S1, GetSize(sig)); bool use_mask = false; for (int i = 0; i < GetSize(sig); i++) if (val[i] != State::S0 && val[i] != State::S1) { - val[i] = State::S0; - mask[i] = State::S0; + val.bits()[i] = State::S0; + mask.bits()[i] = State::S0; use_mask = true; } if (use_mask) @@ -1359,10 +1361,10 @@ struct Smt2Worker for (int k = 0; k < GetSize(initword); k++) { if (initword[k] == State::S0 || initword[k] == State::S1) { gen_init_constr = true; - initmask[k] = State::S1; + initmask.bits()[k] = State::S1; } else { - initmask[k] = State::S0; - initword[k] = State::S0; + initmask.bits()[k] = State::S0; + initword.bits()[k] = State::S0; } } @@ -1829,7 +1831,7 @@ struct Smt2Backend : public Backend { } } - *f << stringf("; SMT-LIBv2 description generated by %s\n", yosys_version_str); + *f << stringf("; SMT-LIBv2 description generated by %s\n", yosys_maybe_version()); if (!bvmode) *f << stringf("; yosys-smt2-nobv\n"); diff --git a/backends/smt2/smtbmc.py b/backends/smt2/smtbmc.py index c3bdcebbe..d17bad3fb 100644 --- a/backends/smt2/smtbmc.py +++ b/backends/smt2/smtbmc.py @@ -1454,6 +1454,10 @@ def write_trace(steps_start, steps_stop, index, allregs=False): if outywfile is not None: write_yw_trace(steps, index, allregs) +def escape_path_segment(segment): + if "." in segment: + return f"\\{segment} " + return segment def print_failed_asserts_worker(mod, state, path, extrainfo, infomap, infokey=()): assert mod in smt.modinfo @@ -1464,7 +1468,8 @@ def print_failed_asserts_worker(mod, state, path, extrainfo, infomap, infokey=() for cellname, celltype in smt.modinfo[mod].cells.items(): cell_infokey = (mod, cellname, infokey) - if print_failed_asserts_worker(celltype, "(|%s_h %s| %s)" % (mod, cellname, state), path + "." + cellname, extrainfo, infomap, cell_infokey): + cell_path = path + "." + escape_path_segment(cellname) + if print_failed_asserts_worker(celltype, "(|%s_h %s| %s)" % (mod, cellname, state), cell_path, extrainfo, infomap, cell_infokey): found_failed_assert = True for assertfun, assertinfo in smt.modinfo[mod].asserts.items(): @@ -1497,7 +1502,7 @@ def print_anyconsts_worker(mod, state, path): assert mod in smt.modinfo for cellname, celltype in smt.modinfo[mod].cells.items(): - print_anyconsts_worker(celltype, "(|%s_h %s| %s)" % (mod, cellname, state), path + "." + cellname) + print_anyconsts_worker(celltype, "(|%s_h %s| %s)" % (mod, cellname, state), path + "." + escape_path_segment(cellname)) for fun, info in smt.modinfo[mod].anyconsts.items(): if info[1] is None: @@ -1517,18 +1522,21 @@ def print_anyconsts(state): print_anyconsts_worker(topmod, "s%d" % state, topmod) -def get_cover_list(mod, base): +def get_cover_list(mod, base, path=None): + path = path or mod assert mod in smt.modinfo cover_expr = list() + # A tuple of path and cell name cover_desc = list() for expr, desc in smt.modinfo[mod].covers.items(): cover_expr.append("(ite (|%s| %s) #b1 #b0)" % (expr, base)) - cover_desc.append(desc) + cover_desc.append((path, desc)) for cell, submod in smt.modinfo[mod].cells.items(): - e, d = get_cover_list(submod, "(|%s_h %s| %s)" % (mod, cell, base)) + cell_path = path + "." + escape_path_segment(cell) + e, d = get_cover_list(submod, "(|%s_h %s| %s)" % (mod, cell, base), cell_path) cover_expr += e cover_desc += d @@ -1544,7 +1552,8 @@ def get_assert_map(mod, base, path, key_base=()): assert_map[(expr, key_base)] = ("(|%s| %s)" % (expr, base), path, desc) for cell, submod in smt.modinfo[mod].cells.items(): - assert_map.update(get_assert_map(submod, "(|%s_h %s| %s)" % (mod, cell, base), path + "." + cell, (mod, cell, key_base))) + cell_path = path + "." + escape_path_segment(cell) + assert_map.update(get_assert_map(submod, "(|%s_h %s| %s)" % (mod, cell, base), cell_path, (mod, cell, key_base))) return assert_map @@ -1903,7 +1912,9 @@ elif covermode: new_cover_mask.append(cover_mask[i]) continue - print_msg("Reached cover statement at %s in step %d." % (cover_desc[i], step)) + path = cover_desc[i][0] + name = cover_desc[i][1] + print_msg("Reached cover statement in step %d at %s: %s" % (step, path, name)) new_cover_mask.append("0") cover_mask = "".join(new_cover_mask) @@ -1933,7 +1944,7 @@ elif covermode: if "1" in cover_mask: for i in range(len(cover_mask)): if cover_mask[i] == "1": - print_msg("Unreached cover statement at %s." % cover_desc[i]) + print_msg("Unreached cover statement at %s: %s" % (cover_desc[i][0], cover_desc[i][1])) else: # not tempind, covermode active_assert_keys = get_assert_keys() diff --git a/backends/smt2/smtio.py b/backends/smt2/smtio.py index 6418061ef..b021d0184 100644 --- a/backends/smt2/smtio.py +++ b/backends/smt2/smtio.py @@ -1217,7 +1217,7 @@ class SmtOpts: def helpmsg(self): return """ -s - set SMT solver: z3, yices, boolector, bitwuzla, cvc4, mathsat, dummy + set SMT solver: z3, yices, boolector, bitwuzla, cvc4, cvc5, mathsat, dummy default: yices -S diff --git a/backends/smt2/test_cells.sh b/backends/smt2/test_cells.sh index 3f84d65a2..33c1b9989 100644 --- a/backends/smt2/test_cells.sh +++ b/backends/smt2/test_cells.sh @@ -21,7 +21,7 @@ EOT for x in $(set +x; ls test_*.il | sort -R); do x=${x%.il} cat > $x.ys <<- EOT - read_ilang $x.il + read_rtlil $x.il copy gold gate cd gate diff --git a/backends/smv/smv.cc b/backends/smv/smv.cc index 44e200384..1c2b2a224 100644 --- a/backends/smv/smv.cc +++ b/backends/smv/smv.cc @@ -797,7 +797,7 @@ struct SmvBackend : public Backend { if (module == nullptr) log_error("Module '%s' not found.\n", stmt[1].c_str()); - *f << stringf("-- SMV description generated by %s\n", yosys_version_str); + *f << stringf("-- SMV description generated by %s\n", yosys_maybe_version()); log("Creating SMV representation of module %s.\n", log_id(module)); SmvWorker worker(module, verbose, *f); @@ -816,7 +816,7 @@ struct SmvBackend : public Backend { if (!modules.empty()) { - *f << stringf("-- SMV description generated by %s\n", yosys_version_str); + *f << stringf("-- SMV description generated by %s\n", yosys_maybe_version()); for (auto module : modules) { log("Creating SMV representation of module %s.\n", log_id(module)); diff --git a/backends/smv/test_cells.sh b/backends/smv/test_cells.sh index 1347b7044..f2c5ff09d 100644 --- a/backends/smv/test_cells.sh +++ b/backends/smv/test_cells.sh @@ -17,11 +17,11 @@ EOT for fn in test_*.il; do ../../../yosys -p " - read_ilang $fn + read_rtlil $fn rename gold gate synth - read_ilang $fn + read_rtlil $fn miter -equiv -flatten gold gate main hierarchy -top main write_smv -tpl template.txt ${fn#.il}.smv diff --git a/backends/spice/spice.cc b/backends/spice/spice.cc index 1160a01a1..e55db95e1 100644 --- a/backends/spice/spice.cc +++ b/backends/spice/spice.cc @@ -215,7 +215,7 @@ struct SpiceBackend : public Backend { if (module->get_bool_attribute(ID::top)) top_module_name = module->name.str(); - *f << stringf("* SPICE netlist generated by %s\n", yosys_version_str); + *f << stringf("* SPICE netlist generated by %s\n", yosys_maybe_version()); *f << stringf("\n"); for (auto module : design->modules()) diff --git a/backends/verilog/verilog_backend.cc b/backends/verilog/verilog_backend.cc index 31bbc996f..070df1543 100644 --- a/backends/verilog/verilog_backend.cc +++ b/backends/verilog/verilog_backend.cc @@ -28,12 +28,71 @@ #include "kernel/ff.h" #include "kernel/mem.h" #include "kernel/fmt.h" +#include "backends/verilog/verilog_backend.h" #include #include #include #include USING_YOSYS_NAMESPACE + +using namespace VERILOG_BACKEND; + +const pool VERILOG_BACKEND::verilog_keywords() { + static const pool res = { + // IEEE 1800-2017 Annex B + "accept_on", "alias", "always", "always_comb", "always_ff", "always_latch", "and", "assert", "assign", "assume", "automatic", "before", + "begin", "bind", "bins", "binsof", "bit", "break", "buf", "bufif0", "bufif1", "byte", "case", "casex", "casez", "cell", "chandle", + "checker", "class", "clocking", "cmos", "config", "const", "constraint", "context", "continue", "cover", "covergroup", "coverpoint", + "cross", "deassign", "default", "defparam", "design", "disable", "dist", "do", "edge", "else", "end", "endcase", "endchecker", + "endclass", "endclocking", "endconfig", "endfunction", "endgenerate", "endgroup", "endinterface", "endmodule", "endpackage", + "endprimitive", "endprogram", "endproperty", "endsequence", "endspecify", "endtable", "endtask", "enum", "event", "eventually", + "expect", "export", "extends", "extern", "final", "first_match", "for", "force", "foreach", "forever", "fork", "forkjoin", "function", + "generate", "genvar", "global", "highz0", "highz1", "if", "iff", "ifnone", "ignore_bins", "illegal_bins", "implements", "implies", + "import", "incdir", "include", "initial", "inout", "input", "inside", "instance", "int", "integer", "interconnect", "interface", + "intersect", "join", "join_any", "join_none", "large", "let", "liblist", "library", "local", "localparam", "logic", "longint", + "macromodule", "matches", "medium", "modport", "module", "nand", "negedge", "nettype", "new", "nexttime", "nmos", "nor", + "noshowcancelled", "not", "notif0", "notif1", "null", "or", "output", "package", "packed", "parameter", "pmos", "posedge", "primitive", + "priority", "program", "property", "protected", "pull0", "pull1", "pulldown", "pullup", "pulsestyle_ondetect", "pulsestyle_onevent", + "pure", "rand", "randc", "randcase", "randsequence", "rcmos", "real", "realtime", "ref", "reg", "reject_on", "release", "repeat", + "restrict", "return", "rnmos", "rpmos", "rtran", "rtranif0", "rtranif1", "s_always", "s_eventually", "s_nexttime", "s_until", + "s_until_with", "scalared", "sequence", "shortint", "shortreal", "showcancelled", "signed", "small", "soft", "solve", "specify", + "specparam", "static", "string", "strong", "strong0", "strong1", "struct", "super", "supply0", "supply1", "sync_accept_on", + "sync_reject_on", "table", "tagged", "task", "this", "throughout", "time", "timeprecision", "timeunit", "tran", "tranif0", "tranif1", + "tri", "tri0", "tri1", "triand", "trior", "trireg", "type", "typedef", "union", "unique", "unique0", "unsigned", "until", "until_with", + "untyped", "use", "uwire", "var", "vectored", "virtual", "void", "wait", "wait_order", "wand", "weak", "weak0", "weak1", "while", + "wildcard", "wire", "with", "within", "wor", "xnor", "xor", + }; + return res; +} + +bool VERILOG_BACKEND::char_is_verilog_escaped(char c) { + if ('0' <= c && c <= '9') + return false; + if ('a' <= c && c <= 'z') + return false; + if ('A' <= c && c <= 'Z') + return false; + if (c == '_') + return false; + + return true; +} + +bool VERILOG_BACKEND::id_is_verilog_escaped(const std::string &str) { + if ('0' <= str[0] && str[0] <= '9') + return true; + + for (int i = 0; str[i]; i++) + if (char_is_verilog_escaped(str[i])) + return true; + + if (verilog_keywords().count(str)) + return true; + + return false; +} + PRIVATE_NAMESPACE_BEGIN bool verbose, norename, noattr, attr2comment, noexpr, nodec, nohex, nostr, extmem, defparam, decimal, siminit, systemverilog, simple_lhs, noparallelcase; @@ -105,7 +164,6 @@ std::string next_auto_id() std::string id(RTLIL::IdString internal_id, bool may_rename = true) { const char *str = internal_id.c_str(); - bool do_escape = false; if (may_rename && auto_name_map.count(internal_id) != 0) return stringf("%s_%0*d_", auto_prefix.c_str(), auto_name_digits, auto_name_offset + auto_name_map[internal_id]); @@ -113,51 +171,7 @@ std::string id(RTLIL::IdString internal_id, bool may_rename = true) if (*str == '\\') str++; - if ('0' <= *str && *str <= '9') - do_escape = true; - - for (int i = 0; str[i]; i++) - { - if ('0' <= str[i] && str[i] <= '9') - continue; - if ('a' <= str[i] && str[i] <= 'z') - continue; - if ('A' <= str[i] && str[i] <= 'Z') - continue; - if (str[i] == '_') - continue; - do_escape = true; - break; - } - - static const pool keywords = { - // IEEE 1800-2017 Annex B - "accept_on", "alias", "always", "always_comb", "always_ff", "always_latch", "and", "assert", "assign", "assume", "automatic", "before", - "begin", "bind", "bins", "binsof", "bit", "break", "buf", "bufif0", "bufif1", "byte", "case", "casex", "casez", "cell", "chandle", - "checker", "class", "clocking", "cmos", "config", "const", "constraint", "context", "continue", "cover", "covergroup", "coverpoint", - "cross", "deassign", "default", "defparam", "design", "disable", "dist", "do", "edge", "else", "end", "endcase", "endchecker", - "endclass", "endclocking", "endconfig", "endfunction", "endgenerate", "endgroup", "endinterface", "endmodule", "endpackage", - "endprimitive", "endprogram", "endproperty", "endsequence", "endspecify", "endtable", "endtask", "enum", "event", "eventually", - "expect", "export", "extends", "extern", "final", "first_match", "for", "force", "foreach", "forever", "fork", "forkjoin", "function", - "generate", "genvar", "global", "highz0", "highz1", "if", "iff", "ifnone", "ignore_bins", "illegal_bins", "implements", "implies", - "import", "incdir", "include", "initial", "inout", "input", "inside", "instance", "int", "integer", "interconnect", "interface", - "intersect", "join", "join_any", "join_none", "large", "let", "liblist", "library", "local", "localparam", "logic", "longint", - "macromodule", "matches", "medium", "modport", "module", "nand", "negedge", "nettype", "new", "nexttime", "nmos", "nor", - "noshowcancelled", "not", "notif0", "notif1", "null", "or", "output", "package", "packed", "parameter", "pmos", "posedge", "primitive", - "priority", "program", "property", "protected", "pull0", "pull1", "pulldown", "pullup", "pulsestyle_ondetect", "pulsestyle_onevent", - "pure", "rand", "randc", "randcase", "randsequence", "rcmos", "real", "realtime", "ref", "reg", "reject_on", "release", "repeat", - "restrict", "return", "rnmos", "rpmos", "rtran", "rtranif0", "rtranif1", "s_always", "s_eventually", "s_nexttime", "s_until", - "s_until_with", "scalared", "sequence", "shortint", "shortreal", "showcancelled", "signed", "small", "soft", "solve", "specify", - "specparam", "static", "string", "strong", "strong0", "strong1", "struct", "super", "supply0", "supply1", "sync_accept_on", - "sync_reject_on", "table", "tagged", "task", "this", "throughout", "time", "timeprecision", "timeunit", "tran", "tranif0", "tranif1", - "tri", "tri0", "tri1", "triand", "trior", "trireg", "type", "typedef", "union", "unique", "unique0", "unsigned", "until", "until_with", - "untyped", "use", "uwire", "var", "vectored", "virtual", "void", "wait", "wait_order", "wand", "weak", "weak0", "weak1", "while", - "wildcard", "wire", "with", "within", "wor", "xnor", "xor", - }; - if (keywords.count(str)) - do_escape = true; - - if (do_escape) + if (id_is_verilog_escaped(str)) return "\\" + std::string(str) + " "; return std::string(str); } @@ -191,7 +205,7 @@ void dump_const(std::ostream &f, const RTLIL::Const &data, int width = -1, int o { bool set_signed = (data.flags & RTLIL::CONST_FLAG_SIGNED) != 0; if (width < 0) - width = data.bits.size() - offset; + width = data.size() - offset; if (width == 0) { // See IEEE 1364-2005 Clause 5.1.14. f << "{0{1'b0}}"; @@ -199,14 +213,14 @@ void dump_const(std::ostream &f, const RTLIL::Const &data, int width = -1, int o } if (nostr) goto dump_hex; - if ((data.flags & RTLIL::CONST_FLAG_STRING) == 0 || width != (int)data.bits.size()) { + if ((data.flags & RTLIL::CONST_FLAG_STRING) == 0 || width != (int)data.size()) { if (width == 32 && !no_decimal && !nodec) { int32_t val = 0; for (int i = offset+width-1; i >= offset; i--) { - log_assert(i < (int)data.bits.size()); - if (data.bits[i] != State::S0 && data.bits[i] != State::S1) + log_assert(i < (int)data.size()); + if (data[i] != State::S0 && data[i] != State::S1) goto dump_hex; - if (data.bits[i] == State::S1) + if (data[i] == State::S1) val |= 1 << (i - offset); } if (decimal) @@ -221,8 +235,8 @@ void dump_const(std::ostream &f, const RTLIL::Const &data, int width = -1, int o goto dump_bin; vector bin_digits, hex_digits; for (int i = offset; i < offset+width; i++) { - log_assert(i < (int)data.bits.size()); - switch (data.bits[i]) { + log_assert(i < (int)data.size()); + switch (data[i]) { case State::S0: bin_digits.push_back('0'); break; case State::S1: bin_digits.push_back('1'); break; case RTLIL::Sx: bin_digits.push_back('x'); break; @@ -275,8 +289,8 @@ void dump_const(std::ostream &f, const RTLIL::Const &data, int width = -1, int o if (width == 0) f << stringf("0"); for (int i = offset+width-1; i >= offset; i--) { - log_assert(i < (int)data.bits.size()); - switch (data.bits[i]) { + log_assert(i < (int)data.size()); + switch (data[i]) { case State::S0: f << stringf("0"); break; case State::S1: f << stringf("1"); break; case RTLIL::Sx: f << stringf("x"); break; @@ -318,10 +332,10 @@ void dump_reg_init(std::ostream &f, SigSpec sig) for (auto bit : active_sigmap(sig)) { if (active_initdata.count(bit)) { - initval.bits.push_back(active_initdata.at(bit)); + initval.bits().push_back(active_initdata.at(bit)); gotinit = true; } else { - initval.bits.push_back(State::Sx); + initval.bits().push_back(State::Sx); } } @@ -383,6 +397,7 @@ void dump_attributes(std::ostream &f, std::string indent, dictfirst == ID::single_bit_vector) continue; if (it->first == ID::init && regattr) continue; f << stringf("%s" "%s %s", indent.c_str(), as_comment ? "/*" : "(*", id(it->first).c_str()); f << stringf(" = "); @@ -419,6 +434,9 @@ void dump_wire(std::ostream &f, std::string indent, RTLIL::Wire *wire) range = stringf(" [%d:%d]", wire->start_offset, wire->width - 1 + wire->start_offset); else range = stringf(" [%d:%d]", wire->width - 1 + wire->start_offset, wire->start_offset); + } else { + if (wire->attributes.count(ID::single_bit_vector)) + range = stringf(" [%d:%d]", wire->start_offset, wire->start_offset); } if (wire->port_input && !wire->port_output) f << stringf("%s" "input%s %s;\n", indent.c_str(), range.c_str(), id(wire->name).c_str()); @@ -751,7 +769,7 @@ void dump_memory(std::ostream &f, std::string indent, Mem &mem) if (port.wide_log2) { Const addr_lo; for (int i = 0; i < port.wide_log2; i++) - addr_lo.bits.push_back(State(sub >> i & 1)); + addr_lo.bits().push_back(State(sub >> i & 1)); os << "{"; os << temp_id; os << ", "; @@ -1044,16 +1062,23 @@ void dump_cell_expr_print(std::ostream &f, std::string indent, const RTLIL::Cell void dump_cell_expr_check(std::ostream &f, std::string indent, const RTLIL::Cell *cell) { std::string flavor = cell->getParam(ID(FLAVOR)).decode_string(); + std::string label = ""; + if (cell->name.isPublic()) { + label = stringf("%s: ", id(cell->name).c_str()); + } + if (flavor == "assert") - f << stringf("%s" "assert (", indent.c_str()); + f << stringf("%s" "%s" "assert (", indent.c_str(), label.c_str()); else if (flavor == "assume") - f << stringf("%s" "assume (", indent.c_str()); + f << stringf("%s" "%s" "assume (", indent.c_str(), label.c_str()); else if (flavor == "live") - f << stringf("%s" "assert (eventually ", indent.c_str()); + f << stringf("%s" "%s" "assert (eventually ", indent.c_str(), label.c_str()); else if (flavor == "fair") - f << stringf("%s" "assume (eventually ", indent.c_str()); + f << stringf("%s" "%s" "assume (eventually ", indent.c_str(), label.c_str()); else if (flavor == "cover") - f << stringf("%s" "cover (", indent.c_str()); + f << stringf("%s" "%s" "cover (", indent.c_str(), label.c_str()); + else + log_abort(); dump_sigspec(f, cell->getPort(ID::A)); f << stringf(");\n"); } @@ -1071,7 +1096,7 @@ bool dump_cell_expr(std::ostream &f, std::string indent, RTLIL::Cell *cell) return true; } - if (cell->type == ID($_BUF_)) { + if (cell->type.in(ID($_BUF_), ID($buf))) { f << stringf("%s" "assign ", indent.c_str()); dump_sigspec(f, cell->getPort(ID::Y)); f << stringf(" = "); @@ -1138,9 +1163,9 @@ bool dump_cell_expr(std::ostream &f, std::string indent, RTLIL::Cell *cell) dump_sigspec(f, cell->getPort(ID::Y)); f << stringf(" = ~(("); dump_cell_expr_port(f, cell, "A", false); - f << stringf(cell->type == ID($_AOI3_) ? " & " : " | "); + f << (cell->type == ID($_AOI3_) ? " & " : " | "); dump_cell_expr_port(f, cell, "B", false); - f << stringf(cell->type == ID($_AOI3_) ? ") |" : ") &"); + f << (cell->type == ID($_AOI3_) ? ") |" : ") &"); dump_attributes(f, "", cell->attributes, " "); f << stringf(" "); dump_cell_expr_port(f, cell, "C", false); @@ -1153,13 +1178,13 @@ bool dump_cell_expr(std::ostream &f, std::string indent, RTLIL::Cell *cell) dump_sigspec(f, cell->getPort(ID::Y)); f << stringf(" = ~(("); dump_cell_expr_port(f, cell, "A", false); - f << stringf(cell->type == ID($_AOI4_) ? " & " : " | "); + f << (cell->type == ID($_AOI4_) ? " & " : " | "); dump_cell_expr_port(f, cell, "B", false); - f << stringf(cell->type == ID($_AOI4_) ? ") |" : ") &"); + f << (cell->type == ID($_AOI4_) ? ") |" : ") &"); dump_attributes(f, "", cell->attributes, " "); f << stringf(" ("); dump_cell_expr_port(f, cell, "C", false); - f << stringf(cell->type == ID($_AOI4_) ? " & " : " | "); + f << (cell->type == ID($_AOI4_) ? " & " : " | "); dump_cell_expr_port(f, cell, "D", false); f << stringf("));\n"); return true; @@ -1370,10 +1395,10 @@ bool dump_cell_expr(std::ostream &f, std::string indent, RTLIL::Cell *cell) int s_width = cell->getPort(ID::S).size(); std::string func_name = cellname(cell); - f << stringf("%s" "function [%d:0] %s;\n", indent.c_str(), width-1, func_name.c_str()); - f << stringf("%s" " input [%d:0] a;\n", indent.c_str(), width-1); - f << stringf("%s" " input [%d:0] b;\n", indent.c_str(), s_width*width-1); - f << stringf("%s" " input [%d:0] s;\n", indent.c_str(), s_width-1); + f << stringf("%s" "function [%d:0] %s;\n", indent, width-1, func_name); + f << stringf("%s" " input [%d:0] a;\n", indent, width-1); + f << stringf("%s" " input [%d:0] b;\n", indent, s_width*width-1); + f << stringf("%s" " input [%d:0] s;\n", indent, s_width-1); dump_attributes(f, indent + " ", cell->attributes); if (noparallelcase) @@ -1382,7 +1407,7 @@ bool dump_cell_expr(std::ostream &f, std::string indent, RTLIL::Cell *cell) if (!noattr) f << stringf("%s" " (* parallel_case *)\n", indent.c_str()); f << stringf("%s" " casez (s)", indent.c_str()); - f << stringf(noattr ? " // synopsys parallel_case\n" : "\n"); + f << (noattr ? " // synopsys parallel_case\n" : "\n"); } for (int i = 0; i < s_width; i++) @@ -2332,19 +2357,15 @@ void dump_module(std::ostream &f, std::string indent, RTLIL::Module *module) dump_attributes(f, indent, module->attributes, "\n", /*modattr=*/true); f << stringf("%s" "module %s(", indent.c_str(), id(module->name, false).c_str()); - bool keep_running = true; int cnt = 0; - for (int port_id = 1; keep_running; port_id++) { - keep_running = false; - for (auto wire : module->wires()) { - if (wire->port_id == port_id) { - if (port_id != 1) - f << stringf(", "); - f << stringf("%s", id(wire->name).c_str()); - keep_running = true; - if (cnt==20) { f << stringf("\n"); cnt = 0; } else cnt++; - continue; - } + for (auto port : module->ports) { + Wire *wire = module->wire(port); + if (wire) { + if (port != module->ports[0]) + f << stringf(", "); + f << stringf("%s", id(wire->name).c_str()); + if (cnt==20) { f << stringf("\n"); cnt = 0; } else cnt++; + continue; } } f << stringf(");\n"); @@ -2591,9 +2612,10 @@ struct VerilogBackend : public Backend { Pass::call(design, "clean_zerowidth"); log_pop(); - design->sort(); + design->sort_modules(); + + *f << stringf("/* Generated by %s */\n", yosys_maybe_version()); - *f << stringf("/* Generated by %s */\n", yosys_version_str); for (auto module : design->modules()) { if (module->get_blackbox_attribute() != blackboxes) continue; @@ -2603,6 +2625,7 @@ struct VerilogBackend : public Backend { continue; } log("Dumping module `%s'.\n", module->name.c_str()); + module->sort(); dump_module(*f, "", module); } diff --git a/backends/verilog/verilog_backend.h b/backends/verilog/verilog_backend.h new file mode 100644 index 000000000..7e550a37c --- /dev/null +++ b/backends/verilog/verilog_backend.h @@ -0,0 +1,39 @@ +/* + * yosys -- Yosys Open SYnthesis Suite + * + * Copyright (C) 2012 Claire Xenia Wolf + * + * Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + * + * --- + * + * A simple and straightforward Verilog backend. + * + */ + +#ifndef VERILOG_BACKEND_H +#define VERILOG_BACKEND_H + +#include + +YOSYS_NAMESPACE_BEGIN +namespace VERILOG_BACKEND { + + const pool verilog_keywords(); + bool char_is_verilog_escaped(char c); + bool id_is_verilog_escaped(const std::string &str); + +}; /* namespace VERILOG_BACKEND */ +YOSYS_NAMESPACE_END + +#endif /* VERILOG_BACKEND_H */ diff --git a/docs/Makefile b/docs/Makefile index 21fcd9623..a8874bb83 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -238,7 +238,7 @@ Makefile-%: FORCE $(MAKE) -C $(@D) $(*F) CODE_EXAMPLES := $(wildcard source/code_examples/*/Makefile) -TEST_EXAMPLES := $(addsuffix -all,$(CODE_EXAMPLES)) +TEST_EXAMPLES := $(addsuffix -examples,$(CODE_EXAMPLES)) CLEAN_EXAMPLES := $(addsuffix -clean,$(CODE_EXAMPLES)) test-examples: $(TEST_EXAMPLES) clean-examples: $(CLEAN_EXAMPLES) @@ -252,6 +252,11 @@ images: $(MAKE) -C source/_images $(MAKE) -C source/_images convert +.PHONY: gen +gen: + $(MAKE) examples + $(MAKE) images + .PHONY: reqs reqs: $(PYTHON) -m pip install -r source/requirements.txt diff --git a/docs/source/_images/Makefile b/docs/source/_images/Makefile index 26cc47284..71f52c578 100644 --- a/docs/source/_images/Makefile +++ b/docs/source/_images/Makefile @@ -1,8 +1,14 @@ -all: examples all_tex tidy +all: examples all_tex # set a fake time in pdf generation to prevent unnecessary differences in output FAKETIME := TZ='Z' faketime -f '2022-01-01 00:00:00 x0,001' +ifneq ($(shell :; command -v rsync),) +RSYNC_CP ?= rsync -t +else +RSYNC_CP ?= cp -a +endif + # find all code example makefiles .PHONY: examples CODE_EXAMPLES := ../code_examples/*/Makefile @@ -19,7 +25,7 @@ FORCE: ../%/Makefile: FORCE @make -C $(@D) dots @mkdir -p $* - @find $(@D) -name *.dot -exec rsync -t {} $* \; + @find $(@D) -name *.dot -exec $(RSYNC_CP) {} $* \; # find and build all tex files .PHONY: all_tex diff --git a/docs/source/_images/internals/overview_flow.tex b/docs/source/_images/internals/overview_flow.tex index ac0afde5f..b3f12626a 100644 --- a/docs/source/_images/internals/overview_flow.tex +++ b/docs/source/_images/internals/overview_flow.tex @@ -15,23 +15,23 @@ \tikzstyle{data} = [draw, fill=blue!10, ellipse, minimum height=3em, minimum width=7em, node distance=15em] \node[process] (vlog) {Verilog Frontend}; \node[process, dashed, fill=green!5] (vhdl) [right of=vlog] {VHDL Frontend}; - \node[process] (ilang) [right of=vhdl] {RTLIL Frontend}; + \node[process] (rtlilfe) [right of=vhdl] {RTLIL Frontend}; \node[data] (ast) [below of=vlog, node distance=5em, xshift=7.5em] {AST}; \node[process] (astfe) [below of=ast, node distance=5em] {AST Frontend}; \node[data] (rtlil) [below of=astfe, node distance=5em, xshift=7.5em] {RTLIL}; \node[process] (pass) [right of=rtlil, node distance=5em, xshift=7.5em] {Passes}; \node[process] (vlbe) [below of=rtlil, node distance=7em, xshift=-13em] {Verilog Backend}; - \node[process] (ilangbe) [below of=rtlil, node distance=7em, xshift=0em] {RTLIL Backend}; + \node[process] (rtlilbe) [below of=rtlil, node distance=7em, xshift=0em] {RTLIL Backend}; \node[process, dashed, fill=green!5] (otherbe) [below of=rtlil, node distance=7em, xshift=+13em] {Other Backends}; \draw[-latex] (vlog) -- (ast); \draw[-latex] (vhdl) -- (ast); \draw[-latex] (ast) -- (astfe); \draw[-latex] (astfe) -- (rtlil); - \draw[-latex] (ilang) -- (rtlil); + \draw[-latex] (rtlilfe) -- (rtlil); \draw[latex-latex] (rtlil) -- (pass); \draw[-latex] (rtlil) -- (vlbe); - \draw[-latex] (rtlil) -- (ilangbe); + \draw[-latex] (rtlil) -- (rtlilbe); \draw[-latex] (rtlil) -- (otherbe); \end{tikzpicture} \end{document} diff --git a/docs/source/_static/favico.png b/docs/source/_static/favico.png deleted file mode 100644 index 3f5afba76..000000000 Binary files a/docs/source/_static/favico.png and /dev/null differ diff --git a/docs/source/_static/yosyshq.css b/docs/source/_static/yosyshq.css deleted file mode 100644 index 447c85367..000000000 --- a/docs/source/_static/yosyshq.css +++ /dev/null @@ -1,40 +0,0 @@ -/* Don't hide the right sidebar as we're placing our fixed links there */ -aside.no-toc { - display: block !important; -} - -/* Colorful headings */ -h1 { - color: var(--color-brand-primary); - } - -h2, h3, h4, h5, h6 { - color: var(--color-brand-content); -} - -/* Use a different color for external links */ -a.external { - color: var(--color-brand-primary) !important; -} - -.wy-table-responsive table td { - white-space: normal; -} - -th { - text-align: left; -} - -body[data-theme="dark"] { - .invert-helper { - filter: url("data:image/svg+xml,#f"); - } -} - -@media (prefers-color-scheme: dark) { - body:not([data-theme="light"]) { - .invert-helper { - filter: url("data:image/svg+xml,#f"); - } - } -} \ No newline at end of file diff --git a/docs/source/_templates/page.html b/docs/source/_templates/page.html deleted file mode 100644 index d830124c1..000000000 --- a/docs/source/_templates/page.html +++ /dev/null @@ -1,44 +0,0 @@ -{# - -See https://github.com/pradyunsg/furo/blob/main/src/furo/theme/furo/page.html for the original -block this is overwriting. - -The part that is customized is between the "begin of custom part" and "end of custom part" -comments below. It uses the same styles as the existing right sidebar code. - -#} -{% extends "furo/page.html" %} -{% block right_sidebar %} -
- {# begin of custom part #} -
- - YosysHQ - -
-
-
- -
-
- {# end of custom part #} - {% if not furo_hide_toc %} -
- - {{ _("On this page") }} - -
-
-
- {{ toc }} -
-
- {% endif %} -
-{% endblock %} - \ No newline at end of file diff --git a/docs/source/appendix.rst b/docs/source/appendix.rst deleted file mode 100644 index 0b0a2d15b..000000000 --- a/docs/source/appendix.rst +++ /dev/null @@ -1,18 +0,0 @@ -Appendix -======== - -.. toctree:: - :maxdepth: 2 - :includehidden: - - appendix/primer - appendix/auxlibs - appendix/auxprogs - - bib - -.. toctree:: - :maxdepth: 1 - :includehidden: - - cmd_ref diff --git a/docs/source/appendix/auxlibs.rst b/docs/source/appendix/auxlibs.rst index 321cb52c4..8c78ed6b3 100644 --- a/docs/source/appendix/auxlibs.rst +++ b/docs/source/appendix/auxlibs.rst @@ -29,7 +29,7 @@ ezSAT The files in ``libs/ezsat`` provide a library for simplifying generating CNF formulas for SAT solvers. It also contains bindings of MiniSAT. The ezSAT -library is written by C. Wolf. It is used by the :cmd:ref:`sat` pass (see +library is written by C. Wolf. It is used by the `sat` pass (see :doc:`/cmd/sat`). fst @@ -37,22 +37,22 @@ fst ``libfst`` files from `gtkwave`_ are included in ``libs/fst`` to support reading/writing signal traces from/to the GTKWave developed FST format. This is -primarily used in the :cmd:ref:`sim` command. +primarily used in the `sim` command. .. _gtkwave: https://github.com/gtkwave/gtkwave json11 ------ -For reading/writing designs from/to JSON, :cmd:ref:`read_json` and -:cmd:ref:`write_json` should be used. For everything else there is the `json11 +For reading/writing designs from/to JSON, `read_json` and +`write_json` should be used. For everything else there is the `json11 library`_: json11 is a tiny JSON library for C++11, providing JSON parsing and serialization. -This library is used for outputting machine-readable statistics (:cmd:ref:`stat` -with ``-json`` flag), using the RPC frontend (:cmd:ref:`connect_rpc`), and the +This library is used for outputting machine-readable statistics (`stat` +with ``-json`` flag), using the RPC frontend (`connect_rpc`), and the yosys-witness ``yw`` format. .. _json11 library: https://github.com/dropbox/json11 @@ -61,7 +61,7 @@ MiniSAT ------- The files in ``libs/minisat`` provide a high-performance SAT solver, used by the -:cmd:ref:`sat` command. +`sat` command. SHA1 ---- diff --git a/docs/source/appendix/env_vars.rst b/docs/source/appendix/env_vars.rst index 26cc37c81..69e86c922 100644 --- a/docs/source/appendix/env_vars.rst +++ b/docs/source/appendix/env_vars.rst @@ -3,7 +3,7 @@ Yosys environment variables ``HOME`` Yosys command history is stored in :file:`$HOME/.yosys_history`. Graphics - (from :cmd:ref:`show` and :cmd:ref:`viz` commands) will output to this + (from `show` and `viz` commands) will output to this directory by default. This environment variable is also used in some cases for resolving filenames with :file:`~`. diff --git a/docs/source/appendix/primer.rst b/docs/source/appendix/primer.rst index 50656af78..f54f99e52 100644 --- a/docs/source/appendix/primer.rst +++ b/docs/source/appendix/primer.rst @@ -72,7 +72,7 @@ circuits. Tools exist to synthesize high level code (usually in the form of C/C++/SystemC code with additional metadata) to behavioural HDL code (usually in the form of Verilog or VHDL code). Aside from the many commercial tools for high level -synthesis there are also a number of FOSS tools for high level synthesis . +synthesis there are also a number of FOSS tools for high level synthesis. Behavioural level ~~~~~~~~~~~~~~~~~ @@ -185,7 +185,7 @@ advantage that it has a unique normalized form. The latter has much better worst case performance and is therefore better suited for the synthesis of large logic functions. -Good FOSS tools exists for multi-level logic synthesis . +Good FOSS tools exists for multi-level logic synthesis. Yosys contains basic logic synthesis functionality but can also use ABC for the logic synthesis step. Using ABC is recommended. @@ -221,7 +221,7 @@ design description as input and generates an RTL, logical gate or physical gate level description of the design as output. Yosys' main strengths are behavioural and RTL synthesis. A wide range of commands (synthesis passes) exist within Yosys that can be used to perform a wide range of synthesis tasks within the -domain of behavioural, rtl and logic synthesis. Yosys is designed to be +domain of behavioural, RTL and logic synthesis. Yosys is designed to be extensible and therefore is a good basis for implementing custom synthesis tools for specialised tasks. @@ -572,7 +572,7 @@ of lexical tokens given in :numref:`Tab. %s `. TOK_SEMICOLON \- ============== =============== -The lexer is usually generated by a lexer generator (e.g. flex ) from a +The lexer is usually generated by a lexer generator (e.g. flex) from a description file that is using regular expressions to specify the text pattern that should match the individual tokens. diff --git a/docs/source/yosys_internals/formats/rtlil_text.rst b/docs/source/appendix/rtlil_text.rst similarity index 95% rename from docs/source/yosys_internals/formats/rtlil_text.rst rename to docs/source/appendix/rtlil_text.rst index 8b5c10681..b1bc9c582 100644 --- a/docs/source/yosys_internals/formats/rtlil_text.rst +++ b/docs/source/appendix/rtlil_text.rst @@ -223,8 +223,8 @@ Cells Declares a cell, with zero or more attributes, with the given identifier and type in the enclosing module. -Cells perform functions on input signals. See -:doc:`/yosys_internals/formats/cell_library` for a detailed list of cell types. +Cells perform functions on input signals. See :doc:`/cell_index` for a detailed +list of cell types. .. code:: BNF @@ -242,7 +242,7 @@ Processes Declares a process, with zero or more attributes, with the given identifier in the enclosing module. The body of a process consists of zero or more -assignments, exactly one switch, and zero or more syncs. +assignments followed by zero or more switches and zero or more syncs. See :ref:`sec:rtlil_process` for an overview of processes. @@ -250,7 +250,7 @@ See :ref:`sec:rtlil_process` for an overview of processes. ::= * ::= process - ::= * ? * * + ::= * * * ::= assign ::= ::= @@ -262,8 +262,8 @@ Switches Switches test a signal for equality against a list of cases. Each case specifies a comma-separated list of signals to check against. If there are no signals in the list, then the case is the default case. The body of a case consists of zero -or more switches and assignments. Both switches and cases may have zero or more -attributes. +or more assignments followed by zero or more switches. Both switches and cases +may have zero or more attributes. .. code:: BNF @@ -272,7 +272,7 @@ attributes. ::= * ::= case ? ::= (, )* - ::= ( | )* + ::= * * ::= end Syncs diff --git a/docs/source/cell/gate_comb_combined.rst b/docs/source/cell/gate_comb_combined.rst new file mode 100644 index 000000000..1a1f548cc --- /dev/null +++ b/docs/source/cell/gate_comb_combined.rst @@ -0,0 +1,53 @@ +.. role:: verilog(code) + :language: Verilog + +Combinatorial cells (combined) +------------------------------ + +These cells combine two or more combinatorial cells (simple) into a single cell. + +.. table:: Cell types for gate level combinatorial cells (combined) + + ======================================= ============= + Verilog Cell Type + ======================================= ============= + :verilog:`Y = A & ~B` `$_ANDNOT_` + :verilog:`Y = A | ~B` `$_ORNOT_` + :verilog:`Y = ~((A & B) | C)` `$_AOI3_` + :verilog:`Y = ~((A | B) & C)` `$_OAI3_` + :verilog:`Y = ~((A & B) | (C & D))` `$_AOI4_` + :verilog:`Y = ~((A | B) & (C | D))` `$_OAI4_` + :verilog:`Y = ~(S ? B : A)` `$_NMUX_` + (see below) `$_MUX4_` + (see below) `$_MUX8_` + (see below) `$_MUX16_` + ======================================= ============= + +The `$_MUX4_`, `$_MUX8_` and `$_MUX16_` cells are used to model wide muxes, and +correspond to the following Verilog code: + +.. code-block:: verilog + :force: + + // $_MUX4_ + assign Y = T ? (S ? D : C) : + (S ? B : A); + // $_MUX8_ + assign Y = U ? T ? (S ? H : G) : + (S ? F : E) : + T ? (S ? D : C) : + (S ? B : A); + // $_MUX16_ + assign Y = V ? U ? T ? (S ? P : O) : + (S ? N : M) : + T ? (S ? L : K) : + (S ? J : I) : + U ? T ? (S ? H : G) : + (S ? F : E) : + T ? (S ? D : C) : + (S ? B : A); + +.. autocellgroup:: comb_combined + :members: + :source: + :linenos: diff --git a/docs/source/cell/gate_comb_simple.rst b/docs/source/cell/gate_comb_simple.rst new file mode 100644 index 000000000..f45e64496 --- /dev/null +++ b/docs/source/cell/gate_comb_simple.rst @@ -0,0 +1,26 @@ +.. role:: verilog(code) + :language: Verilog + +Combinatorial cells (simple) +---------------------------- + +.. table:: Cell types for gate level combinatorial cells (simple) + + ======================================= ============= + Verilog Cell Type + ======================================= ============= + :verilog:`Y = A` `$_BUF_` + :verilog:`Y = ~A` `$_NOT_` + :verilog:`Y = A & B` `$_AND_` + :verilog:`Y = ~(A & B)` `$_NAND_` + :verilog:`Y = A | B` `$_OR_` + :verilog:`Y = ~(A | B)` `$_NOR_` + :verilog:`Y = A ^ B` `$_XOR_` + :verilog:`Y = ~(A ^ B)` `$_XNOR_` + :verilog:`Y = S ? B : A` `$_MUX_` + ======================================= ============= + +.. autocellgroup:: comb_simple + :members: + :source: + :linenos: diff --git a/docs/source/cell/gate_other.rst b/docs/source/cell/gate_other.rst new file mode 100644 index 000000000..bac26094e --- /dev/null +++ b/docs/source/cell/gate_other.rst @@ -0,0 +1,8 @@ +Other gate-level cells +---------------------- + +.. autocellgroup:: gate_other + :caption: Other gate-level cells + :members: + :source: + :linenos: diff --git a/docs/source/cell/gate_reg_ff.rst b/docs/source/cell/gate_reg_ff.rst new file mode 100644 index 000000000..2a31a3f09 --- /dev/null +++ b/docs/source/cell/gate_reg_ff.rst @@ -0,0 +1,231 @@ +.. role:: verilog(code) + :language: Verilog + +Flip-flop cells +--------------- + +The cell types `$_DFF_N_` and `$_DFF_P_` represent d-type flip-flops. + +.. table:: Cell types for basic flip-flops + + ======================================= ============= + Verilog Cell Type + ======================================= ============= + :verilog:`always @(negedge C) Q <= D` `$_DFF_N_` + :verilog:`always @(posedge C) Q <= D` `$_DFF_P_` + ======================================= ============= + +The cell types ``$_DFFE_[NP][NP]_`` implement d-type flip-flops with enable. The +values in the table for these cell types relate to the following Verilog code +template. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C) + if (EN == EN_LVL) + Q <= D; + + +.. table:: Cell types for gate level logic networks (FFs with enable) + :name: tab:CellLib_gates_dffe + + ================== ============= ============ + :math:`ClkEdge` :math:`EnLvl` Cell Type + ================== ============= ============ + :verilog:`negedge` ``0`` `$_DFFE_NN_` + :verilog:`negedge` ``1`` `$_DFFE_NP_` + :verilog:`posedge` ``0`` `$_DFFE_PN_` + :verilog:`posedge` ``1`` `$_DFFE_PP_` + ================== ============= ============ + +The cell types ``$_DFF_[NP][NP][01]_`` implement d-type flip-flops with +asynchronous reset. The values in the table for these cell types relate to the +following Verilog code template, where ``RST_EDGE`` is ``posedge`` if +``RST_LVL`` if ``1``, and ``negedge`` otherwise. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C, RST_EDGE R) + if (R == RST_LVL) + Q <= RST_VAL; + else + Q <= D; + +The cell types ``$_SDFF_[NP][NP][01]_`` implement d-type flip-flops with +synchronous reset. The values in the table for these cell types relate to the +following Verilog code template: + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C) + if (R == RST_LVL) + Q <= RST_VAL; + else + Q <= D; + +.. table:: Cell types for gate level logic networks (FFs with reset) + :name: tab:CellLib_gates_adff + + ================== ============== ============== =========================== + :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` Cell Type + ================== ============== ============== =========================== + :verilog:`negedge` ``0`` ``0`` `$_DFF_NN0_`, `$_SDFF_NN0_` + :verilog:`negedge` ``0`` ``1`` `$_DFF_NN1_`, `$_SDFF_NN1_` + :verilog:`negedge` ``1`` ``0`` `$_DFF_NP0_`, `$_SDFF_NP0_` + :verilog:`negedge` ``1`` ``1`` `$_DFF_NP1_`, `$_SDFF_NP1_` + :verilog:`posedge` ``0`` ``0`` `$_DFF_PN0_`, `$_SDFF_PN0_` + :verilog:`posedge` ``0`` ``1`` `$_DFF_PN1_`, `$_SDFF_PN1_` + :verilog:`posedge` ``1`` ``0`` `$_DFF_PP0_`, `$_SDFF_PP0_` + :verilog:`posedge` ``1`` ``1`` `$_DFF_PP1_`, `$_SDFF_PP1_` + ================== ============== ============== =========================== + +The cell types ``$_DFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with +asynchronous reset and enable. The values in the table for these cell types +relate to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` +if ``RST_LVL`` if ``1``, and ``negedge`` otherwise. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C, RST_EDGE R) + if (R == RST_LVL) + Q <= RST_VAL; + else if (EN == EN_LVL) + Q <= D; + +The cell types ``$_SDFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with +synchronous reset and enable, with reset having priority over enable. The values +in the table for these cell types relate to the following Verilog code template: + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C) + if (R == RST_LVL) + Q <= RST_VAL; + else if (EN == EN_LVL) + Q <= D; + +The cell types ``$_SDFFCE_[NP][NP][01][NP]_`` implement d-type flip-flops with +synchronous reset and enable, with enable having priority over reset. The values +in the table for these cell types relate to the following Verilog code template: + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C) + if (EN == EN_LVL) + if (R == RST_LVL) + Q <= RST_VAL; + else + Q <= D; + + +.. table:: Cell types for gate level logic networks (FFs with reset and enable) + :name: tab:CellLib_gates_adffe + + ================== ============== ============== ============= ================================================= + :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` :math:`EnLvl` Cell Type + ================== ============== ============== ============= ================================================= + :verilog:`negedge` ``0`` ``0`` ``0`` `$_DFFE_NN0N_`, `$_SDFFE_NN0N_`, `$_SDFFCE_NN0N_` + :verilog:`negedge` ``0`` ``0`` ``1`` `$_DFFE_NN0P_`, `$_SDFFE_NN0P_`, `$_SDFFCE_NN0P_` + :verilog:`negedge` ``0`` ``1`` ``0`` `$_DFFE_NN1N_`, `$_SDFFE_NN1N_`, `$_SDFFCE_NN1N_` + :verilog:`negedge` ``0`` ``1`` ``1`` `$_DFFE_NN1P_`, `$_SDFFE_NN1P_`, `$_SDFFCE_NN1P_` + :verilog:`negedge` ``1`` ``0`` ``0`` `$_DFFE_NP0N_`, `$_SDFFE_NP0N_`, `$_SDFFCE_NP0N_` + :verilog:`negedge` ``1`` ``0`` ``1`` `$_DFFE_NP0P_`, `$_SDFFE_NP0P_`, `$_SDFFCE_NP0P_` + :verilog:`negedge` ``1`` ``1`` ``0`` `$_DFFE_NP1N_`, `$_SDFFE_NP1N_`, `$_SDFFCE_NP1N_` + :verilog:`negedge` ``1`` ``1`` ``1`` `$_DFFE_NP1P_`, `$_SDFFE_NP1P_`, `$_SDFFCE_NP1P_` + :verilog:`posedge` ``0`` ``0`` ``0`` `$_DFFE_PN0N_`, `$_SDFFE_PN0N_`, `$_SDFFCE_PN0N_` + :verilog:`posedge` ``0`` ``0`` ``1`` `$_DFFE_PN0P_`, `$_SDFFE_PN0P_`, `$_SDFFCE_PN0P_` + :verilog:`posedge` ``0`` ``1`` ``0`` `$_DFFE_PN1N_`, `$_SDFFE_PN1N_`, `$_SDFFCE_PN1N_` + :verilog:`posedge` ``0`` ``1`` ``1`` `$_DFFE_PN1P_`, `$_SDFFE_PN1P_`, `$_SDFFCE_PN1P_` + :verilog:`posedge` ``1`` ``0`` ``0`` `$_DFFE_PP0N_`, `$_SDFFE_PP0N_`, `$_SDFFCE_PP0N_` + :verilog:`posedge` ``1`` ``0`` ``1`` `$_DFFE_PP0P_`, `$_SDFFE_PP0P_`, `$_SDFFCE_PP0P_` + :verilog:`posedge` ``1`` ``1`` ``0`` `$_DFFE_PP1N_`, `$_SDFFE_PP1N_`, `$_SDFFCE_PP1N_` + :verilog:`posedge` ``1`` ``1`` ``1`` `$_DFFE_PP1P_`, `$_SDFFE_PP1P_`, `$_SDFFCE_PP1P_` + ================== ============== ============== ============= ================================================= + +The cell types ``$_DFFSR_[NP][NP][NP]_`` implement d-type flip-flops with +asynchronous set and reset. The values in the table for these cell types relate +to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` if +``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is ``posedge`` if +``SET_LVL`` if ``1``, ``negedge`` otherwise. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S) + if (R == RST_LVL) + Q <= 0; + else if (S == SET_LVL) + Q <= 1; + else + Q <= D; + +.. table:: Cell types for gate level logic networks (FFs with set and reset) + :name: tab:CellLib_gates_dffsr + + ================== ============== ============== ============== + :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` Cell Type + ================== ============== ============== ============== + :verilog:`negedge` ``0`` ``0`` `$_DFFSR_NNN_` + :verilog:`negedge` ``0`` ``1`` `$_DFFSR_NNP_` + :verilog:`negedge` ``1`` ``0`` `$_DFFSR_NPN_` + :verilog:`negedge` ``1`` ``1`` `$_DFFSR_NPP_` + :verilog:`posedge` ``0`` ``0`` `$_DFFSR_PNN_` + :verilog:`posedge` ``0`` ``1`` `$_DFFSR_PNP_` + :verilog:`posedge` ``1`` ``0`` `$_DFFSR_PPN_` + :verilog:`posedge` ``1`` ``1`` `$_DFFSR_PPP_` + ================== ============== ============== ============== + +The cell types ``$_DFFSRE_[NP][NP][NP][NP]_`` implement d-type flip-flops with +asynchronous set and reset and enable. The values in the table for these cell +types relate to the following Verilog code template, where ``RST_EDGE`` is +``posedge`` if ``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is +``posedge`` if ``SET_LVL`` if ``1``, ``negedge`` otherwise. + +.. code-block:: verilog + :force: + + always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S) + if (R == RST_LVL) + Q <= 0; + else if (S == SET_LVL) + Q <= 1; + else if (E == EN_LVL) + Q <= D; + + +.. table:: Cell types for gate level logic networks (FFs with set and reset and enable) + :name: tab:CellLib_gates_dffsre + + ================== ============== ============== ============= ================ + :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` :math:`EnLvl` Cell Type + ================== ============== ============== ============= ================ + :verilog:`negedge` ``0`` ``0`` ``0`` `$_DFFSRE_NNNN_` + :verilog:`negedge` ``0`` ``0`` ``1`` `$_DFFSRE_NNNP_` + :verilog:`negedge` ``0`` ``1`` ``0`` `$_DFFSRE_NNPN_` + :verilog:`negedge` ``0`` ``1`` ``1`` `$_DFFSRE_NNPP_` + :verilog:`negedge` ``1`` ``0`` ``0`` `$_DFFSRE_NPNN_` + :verilog:`negedge` ``1`` ``0`` ``1`` `$_DFFSRE_NPNP_` + :verilog:`negedge` ``1`` ``1`` ``0`` `$_DFFSRE_NPPN_` + :verilog:`negedge` ``1`` ``1`` ``1`` `$_DFFSRE_NPPP_` + :verilog:`posedge` ``0`` ``0`` ``0`` `$_DFFSRE_PNNN_` + :verilog:`posedge` ``0`` ``0`` ``1`` `$_DFFSRE_PNNP_` + :verilog:`posedge` ``0`` ``1`` ``0`` `$_DFFSRE_PNPN_` + :verilog:`posedge` ``0`` ``1`` ``1`` `$_DFFSRE_PNPP_` + :verilog:`posedge` ``1`` ``0`` ``0`` `$_DFFSRE_PPNN_` + :verilog:`posedge` ``1`` ``0`` ``1`` `$_DFFSRE_PPNP_` + :verilog:`posedge` ``1`` ``1`` ``0`` `$_DFFSRE_PPPN_` + :verilog:`posedge` ``1`` ``1`` ``1`` `$_DFFSRE_PPPP_` + ================== ============== ============== ============= ================ + +.. todo:: flip-flops with async load, ``$_ALDFFE?_[NP]{2,3}_`` + +.. autocellgroup:: reg_ff + :members: + :source: + :linenos: diff --git a/docs/source/cell/gate_reg_latch.rst b/docs/source/cell/gate_reg_latch.rst new file mode 100644 index 000000000..bb01bc74c --- /dev/null +++ b/docs/source/cell/gate_reg_latch.rst @@ -0,0 +1,105 @@ +.. role:: verilog(code) + :language: Verilog + +Latch cells +----------- + +The cell types `$_DLATCH_N_` and `$_DLATCH_P_` represent d-type latches. + +.. table:: Cell types for basic latches + + ======================================= ============= + Verilog Cell Type + ======================================= ============= + :verilog:`always @* if (!E) Q <= D` `$_DLATCH_N_` + :verilog:`always @* if (E) Q <= D` `$_DLATCH_P_` + ======================================= ============= + +The cell types ``$_DLATCH_[NP][NP][01]_`` implement d-type latches with reset. +The values in the table for these cell types relate to the following Verilog +code template: + +.. code-block:: verilog + :force: + + always @* + if (R == RST_LVL) + Q <= RST_VAL; + else if (E == EN_LVL) + Q <= D; + +.. table:: Cell types for gate level logic networks (latches with reset) + :name: tab:CellLib_gates_adlatch + + ============= ============== ============== =============== + :math:`EnLvl` :math:`RstLvl` :math:`RstVal` Cell Type + ============= ============== ============== =============== + ``0`` ``0`` ``0`` `$_DLATCH_NN0_` + ``0`` ``0`` ``1`` `$_DLATCH_NN1_` + ``0`` ``1`` ``0`` `$_DLATCH_NP0_` + ``0`` ``1`` ``1`` `$_DLATCH_NP1_` + ``1`` ``0`` ``0`` `$_DLATCH_PN0_` + ``1`` ``0`` ``1`` `$_DLATCH_PN1_` + ``1`` ``1`` ``0`` `$_DLATCH_PP0_` + ``1`` ``1`` ``1`` `$_DLATCH_PP1_` + ============= ============== ============== =============== + +The cell types ``$_DLATCHSR_[NP][NP][NP]_`` implement d-type latches with set +and reset. The values in the table for these cell types relate to the following +Verilog code template: + +.. code-block:: verilog + :force: + + always @* + if (R == RST_LVL) + Q <= 0; + else if (S == SET_LVL) + Q <= 1; + else if (E == EN_LVL) + Q <= D; + +.. table:: Cell types for gate level logic networks (latches with set and reset) + :name: tab:CellLib_gates_dlatchsr + + ============= ============== ============== ================= + :math:`EnLvl` :math:`SetLvl` :math:`RstLvl` Cell Type + ============= ============== ============== ================= + ``0`` ``0`` ``0`` `$_DLATCHSR_NNN_` + ``0`` ``0`` ``1`` `$_DLATCHSR_NNP_` + ``0`` ``1`` ``0`` `$_DLATCHSR_NPN_` + ``0`` ``1`` ``1`` `$_DLATCHSR_NPP_` + ``1`` ``0`` ``0`` `$_DLATCHSR_PNN_` + ``1`` ``0`` ``1`` `$_DLATCHSR_PNP_` + ``1`` ``1`` ``0`` `$_DLATCHSR_PPN_` + ``1`` ``1`` ``1`` `$_DLATCHSR_PPP_` + ============= ============== ============== ================= + +The cell types ``$_SR_[NP][NP]_`` implement sr-type latches. The values in the +table for these cell types relate to the following Verilog code template: + +.. code-block:: verilog + :force: + + always @* + if (R == RST_LVL) + Q <= 0; + else if (S == SET_LVL) + Q <= 1; + +.. table:: Cell types for gate level logic networks (SR latches) + :name: tab:CellLib_gates_sr + + ============== ============== ========== + :math:`SetLvl` :math:`RstLvl` Cell Type + ============== ============== ========== + ``0`` ``0`` `$_SR_NN_` + ``0`` ``1`` `$_SR_NP_` + ``1`` ``0`` `$_SR_PN_` + ``1`` ``1`` `$_SR_PP_` + ============== ============== ========== + +.. autocellgroup:: reg_latch + :members: + :source: + :linenos: diff --git a/docs/source/cell/index_gate.rst b/docs/source/cell/index_gate.rst new file mode 100644 index 000000000..c9decc045 --- /dev/null +++ b/docs/source/cell/index_gate.rst @@ -0,0 +1,25 @@ +.. _sec:celllib_gates: + +Gate-level cells +---------------- + +For gate level logic networks, fixed function single bit cells are used that do +not provide any parameters. + +Simulation models for these cells can be found in the file +:file:`techlibs/common/simcells.v` in the Yosys source tree. + +In most cases gate level logic networks are created from RTL networks using the +techmap pass. The flip-flop cells from the gate level logic network can be +mapped to physical flip-flop cells from a Liberty file using the dfflibmap pass. +The combinatorial logic cells can be mapped to physical cells from a Liberty +file via ABC using the abc pass. + +.. toctree:: + :maxdepth: 2 + + /cell/gate_comb_simple + /cell/gate_comb_combined + /cell/gate_reg_ff + /cell/gate_reg_latch + /cell/gate_other diff --git a/docs/source/cell/index_word.rst b/docs/source/cell/index_word.rst new file mode 100644 index 000000000..409e20d26 --- /dev/null +++ b/docs/source/cell/index_word.rst @@ -0,0 +1,30 @@ +Word-level cells +---------------- + +Most of the RTL cells closely resemble the operators available in HDLs such as +Verilog or VHDL. Therefore Verilog operators are used in the following sections +to define the behaviour of the RTL cells. + +Note that all RTL cells have parameters indicating the size of inputs and +outputs. When passes modify RTL cells they must always keep the values of these +parameters in sync with the size of the signals connected to the inputs and +outputs. + +Simulation models for the RTL cells can be found in the file +:file:`techlibs/common/simlib.v` in the Yosys source tree. + +.. toctree:: + :maxdepth: 2 + + /cell/word_unary + /cell/word_binary + /cell/word_mux + /cell/word_reg + /cell/word_mem + /cell/word_fsm + /cell/word_arith + /cell/word_logic + /cell/word_spec + /cell/word_formal + /cell/word_debug + /cell/word_wire diff --git a/docs/source/cell/properties.rst b/docs/source/cell/properties.rst new file mode 100644 index 000000000..30c58ee51 --- /dev/null +++ b/docs/source/cell/properties.rst @@ -0,0 +1,21 @@ +Cell properties +--------------- + +.. cell:defprop:: is_evaluable + + These cells are able to be used in conjunction with the `eval` command. Some + passes, such as `opt_expr`, may also be able to perform additional + optimizations on cells which are evaluable. + +.. cell:defprop:: x-aware + + Some passes will treat these cells as the non 'x' aware cell. For example, + during synthesis `$eqx` will typically be treated as `$eq`. + +.. cell:defprop:: x-output + + These cells can produce 'x' output even if all inputs are defined. For + example, a `$div` cell with divisor (``B``) equal to zero has undefined + output. + +Refer to the :ref:`propindex` for the list of cells with a given property. diff --git a/docs/source/cell/word_arith.rst b/docs/source/cell/word_arith.rst new file mode 100644 index 000000000..8e3daa27f --- /dev/null +++ b/docs/source/cell/word_arith.rst @@ -0,0 +1,50 @@ +Coarse arithmetics +------------------ + +.. todo:: Add information about `$alu`, `$fa`, `$macc_v2`, and `$lcu` cells. + +The `$macc` cell type represents a generalized multiply and accumulate +operation. The cell is purely combinational. It outputs the result of summing up +a sequence of products and other injected summands. + +.. code-block:: + + Y = 0 +- a0factor1 * a0factor2 +- a1factor1 * a1factor2 +- ... + + B[0] + B[1] + ... + +The A port consists of concatenated pairs of multiplier inputs ("factors"). A +zero length factor2 acts as a constant 1, turning factor1 into a simple summand. + +In this pseudocode, ``u(foo)`` means an unsigned int that's foo bits long. + +.. code-block:: + + struct A { + u(CONFIG.mul_info[0].factor1_len) a0factor1; + u(CONFIG.mul_info[0].factor2_len) a0factor2; + u(CONFIG.mul_info[1].factor1_len) a1factor1; + u(CONFIG.mul_info[1].factor2_len) a1factor2; + ... + }; + +The cell's ``CONFIG`` parameter determines the layout of cell port ``A``. The +CONFIG parameter carries the following information: + +.. code-block:: + + struct CONFIG { + u4 num_bits; + struct mul_info { + bool is_signed; + bool is_subtract; + u(num_bits) factor1_len; + u(num_bits) factor2_len; + }[num_ports]; + }; + +B is an array of concatenated 1-bit-wide unsigned integers to also be summed up. + +.. autocellgroup:: arith + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_binary.rst b/docs/source/cell/word_binary.rst new file mode 100644 index 000000000..5e1e6cd19 --- /dev/null +++ b/docs/source/cell/word_binary.rst @@ -0,0 +1,91 @@ +.. role:: verilog(code) + :language: Verilog + +Binary operators +~~~~~~~~~~~~~~~~ + +All binary RTL cells have two input ports ``A`` and ``B`` and one output port +``Y``. They also have the following parameters: + +``A_SIGNED`` + Set to a non-zero value if the input ``A`` is signed and therefore should be + sign-extended when needed. + +``A_WIDTH`` + The width of the input port ``A``. + +``B_SIGNED`` + Set to a non-zero value if the input ``B`` is signed and therefore should be + sign-extended when needed. + +``B_WIDTH`` + The width of the input port ``B``. + +``Y_WIDTH`` + The width of the output port ``Y``. + +.. table:: Cell types for binary operators with their corresponding Verilog expressions. + + ======================= =============== ======================= =========== + Verilog Cell Type Verilog Cell Type + ======================= =============== ======================= =========== + :verilog:`Y = A & B` `$and` :verilog:`Y = A ** B` `$pow` + :verilog:`Y = A | B` `$or` :verilog:`Y = A < B` `$lt` + :verilog:`Y = A ^ B` `$xor` :verilog:`Y = A <= B` `$le` + :verilog:`Y = A ~^ B` `$xnor` :verilog:`Y = A == B` `$eq` + :verilog:`Y = A << B` `$shl` :verilog:`Y = A != B` `$ne` + :verilog:`Y = A >> B` `$shr` :verilog:`Y = A >= B` `$ge` + :verilog:`Y = A <<< B` `$sshl` :verilog:`Y = A > B` `$gt` + :verilog:`Y = A >>> B` `$sshr` :verilog:`Y = A + B` `$add` + :verilog:`Y = A && B` `$logic_and` :verilog:`Y = A - B` `$sub` + :verilog:`Y = A || B` `$logic_or` :verilog:`Y = A * B` `$mul` + :verilog:`Y = A === B` `$eqx` :verilog:`Y = A / B` `$div` + :verilog:`Y = A !== B` `$nex` :verilog:`Y = A % B` `$mod` + ``N/A`` `$shift` ``N/A`` `$divfloor` + ``N/A`` `$shiftx` ``N/A`` `$modfloor` + ======================= =============== ======================= =========== + +The `$shl` and `$shr` cells implement logical shifts, whereas the `$sshl` and +`$sshr` cells implement arithmetic shifts. The `$shl` and `$sshl` cells +implement the same operation. All four of these cells interpret the second +operand as unsigned, and require ``B_SIGNED`` to be zero. + +Two additional shift operator cells are available that do not directly +correspond to any operator in Verilog, `$shift` and `$shiftx`. The `$shift` cell +performs a right logical shift if the second operand is positive (or unsigned), +and a left logical shift if it is negative. The `$shiftx` cell performs the same +operation as the `$shift` cell, but the vacated bit positions are filled with +undef (x) bits, and corresponds to the Verilog indexed part-select expression. + +For the binary cells that output a logical value (`$logic_and`, `$logic_or`, +`$eqx`, `$nex`, `$lt`, `$le`, `$eq`, `$ne`, `$ge`, `$gt`), when the ``Y_WIDTH`` +parameter is greater than 1, the output is zero-extended, and only the least +significant bit varies. + +Division and modulo cells are available in two rounding modes. The original +`$div` and `$mod` cells are based on truncating division, and correspond to the +semantics of the verilog ``/`` and ``%`` operators. The `$divfloor` and +`$modfloor` cells represent flooring division and flooring modulo, the latter of +which corresponds to the ``%`` operator in Python. See the following table for a +side-by-side comparison between the different semantics. + +.. table:: Comparison between different rounding modes for division and modulo cells. + + +-----------+--------+-----------+-----------+-----------+-----------+ + | Division | Result | Truncating | Flooring | + +-----------+--------+-----------+-----------+-----------+-----------+ + | | | $div | $mod | $divfloor | $modfloor | + +===========+========+===========+===========+===========+===========+ + | -10 / 3 | -3.3 | -3 | -1 | -4 | 2 | + +-----------+--------+-----------+-----------+-----------+-----------+ + | 10 / -3 | -3.3 | -3 | 1 | -4 | -2 | + +-----------+--------+-----------+-----------+-----------+-----------+ + | -10 / -3 | 3.3 | 3 | -1 | 3 | -1 | + +-----------+--------+-----------+-----------+-----------+-----------+ + | 10 / 3 | 3.3 | 3 | 1 | 3 | 1 | + +-----------+--------+-----------+-----------+-----------+-----------+ + +.. autocellgroup:: binary + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_debug.rst b/docs/source/cell/word_debug.rst new file mode 100644 index 000000000..92c753dbe --- /dev/null +++ b/docs/source/cell/word_debug.rst @@ -0,0 +1,138 @@ +.. role:: verilog(code) + :language: Verilog + +Debugging cells +--------------- + +The `$print` cell is used to log the values of signals, akin to (and +translatable to) the ``$display`` and ``$write`` family of tasks in Verilog. It +has the following parameters: + +``FORMAT`` + The internal format string. The syntax is described below. + +``ARGS_WIDTH`` + The width (in bits) of the signal on the ``ARGS`` port. + +``TRG_ENABLE`` + True if triggered on specific signals defined in ``TRG``; false if triggered + whenever ``ARGS`` or ``EN`` change and ``EN`` is 1. + +If ``TRG_ENABLE`` is true, the following parameters also apply: + +``TRG_WIDTH`` + The number of bits in the ``TRG`` port. + +``TRG_POLARITY`` + For each bit in ``TRG``, 1 if that signal is positive-edge triggered, 0 if + negative-edge triggered. + +``PRIORITY`` + When multiple `$print` or `$check` cells fire on the same trigger, they + execute in descending priority order. + +Ports: + +``TRG`` + The signals that control when this `$print` cell is triggered. + + If the width of this port is zero and ``TRG_ENABLE`` is true, the cell is + triggered during initial evaluation (time zero) only. + +``EN`` + Enable signal for the whole cell. + +``ARGS`` + The values to be displayed, in format string order. + +.. autocellgroup:: debug + :members: + :source: + :linenos: + +Format string syntax +~~~~~~~~~~~~~~~~~~~~ + +The format string syntax resembles Python f-strings. Regular text is passed +through unchanged until a format specifier is reached, starting with a ``{``. + +Format specifiers have the following syntax. Unless noted, all items are +required: + +``{`` + Denotes the start of the format specifier. + +size + Signal size in bits; this many bits are consumed from the ``ARGS`` port by + this specifier. + +``:`` + Separates the size from the remaining items. + +justify + ``>`` for right-justified, ``<`` for left-justified. + +padding + ``0`` for zero-padding, or a space for space-padding. + +width\ *?* + (optional) The number of characters wide to pad to. + +base + * ``b`` for base-2 integers (binary) + * ``o`` for base-8 integers (octal) + * ``d`` for base-10 integers (decimal) + * ``h`` for base-16 integers (hexadecimal) + * ``c`` for ASCII characters/strings + * ``t`` and ``r`` for simulation time (corresponding to :verilog:`$time` and + :verilog:`$realtime`) + +For integers, this item may follow: + +``+``\ *?* + (optional, decimals only) Include a leading plus for non-negative numbers. + This can assist with symmetry with negatives in tabulated output. + +signedness + ``u`` for unsigned, ``s`` for signed. This distinction is only respected + when rendering decimals. + +ASCII characters/strings have no special options, but the signal size must be +divisible by 8. + +For simulation time, the signal size must be zero. + +Finally: + +``}`` + Denotes the end of the format specifier. + +Some example format specifiers: + ++ ``{8:>02hu}`` - 8-bit unsigned integer rendered as hexadecimal, + right-justified, zero-padded to 2 characters wide. ++ ``{32:< 15d+s}`` - 32-bit signed integer rendered as decimal, left-justified, + space-padded to 15 characters wide, positive values prefixed with ``+``. ++ ``{16:< 10hu}`` - 16-bit unsigned integer rendered as hexadecimal, + left-justified, space-padded to 10 characters wide. ++ ``{0:>010t}`` - simulation time, right-justified, zero-padded to 10 characters + wide. + +To include literal ``{`` and ``}`` characters in your format string, use ``{{`` +and ``}}`` respectively. + +It is an error for a format string to consume more or less bits from ``ARGS`` +than the port width. + +Values are never truncated, regardless of the specified width. + +Note that further restrictions on allowable combinations of options may apply +depending on the backend used. + +For example, Verilog does not have a format specifier that allows zero-padding a +string (i.e. more than 1 ASCII character), though zero-padding a single +character is permitted. + +Thus, while the RTLIL format specifier ``{8:>02c}`` translates to ``%02c``, +``{16:>02c}`` cannot be represented in Verilog and will fail to emit. In this +case, ``{16:> 02c}`` must be used, which translates to ``%2s``. diff --git a/docs/source/cell/word_formal.rst b/docs/source/cell/word_formal.rst new file mode 100644 index 000000000..6bfa19656 --- /dev/null +++ b/docs/source/cell/word_formal.rst @@ -0,0 +1,31 @@ +Formal verification cells +------------------------- + +.. role:: yoscrypt(code) + :language: yoscrypt + +.. note:: + + Some front-ends may not support the generic `$check` cell, in such cases + calling :yoscrypt:`chformal -lower` will convert each `$check` cell into it's + equivalent. See `chformal` for more. + +.. todo:: Describe formal cells + + `$check`, `$assert`, `$assume`, `$live`, `$fair`, `$cover`, `$equiv`, + `$initstate`, `$anyconst`, `$anyseq`, `$anyinit`, `$allconst`, and `$allseq`. + + Also `$ff` and `$_FF_` cells. + +.. autocellgroup:: formal + :members: + :source: + :linenos: + +Formal support cells +~~~~~~~~~~~~~~~~~~~~ + +.. autocellgroup:: formal_tag + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_fsm.rst b/docs/source/cell/word_fsm.rst new file mode 100644 index 000000000..e6301bf3b --- /dev/null +++ b/docs/source/cell/word_fsm.rst @@ -0,0 +1,9 @@ +Finite state machines +--------------------- + +.. todo:: Describe `$fsm` cell + +.. autocellgroup:: fsm + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_logic.rst b/docs/source/cell/word_logic.rst new file mode 100644 index 000000000..32945d560 --- /dev/null +++ b/docs/source/cell/word_logic.rst @@ -0,0 +1,46 @@ +Arbitrary logic functions +------------------------- + +The `$lut` cell type implements a single-output LUT (lookup table). It +implements an arbitrary logic function with its ``\LUT`` parameter to map input +port ``\A`` to values of ``\Y`` output port values. In psuedocode: ``Y = +\LUT[A]``. ``\A`` has width set by parameter ``\WIDTH`` and ``\Y`` has a width +of 1. Every logic function with a single bit output has a unique `$lut` +representation. + +The `$sop` cell type implements a sum-of-products expression, also known as +disjunctive normal form (DNF). It implements an arbitrary logic function. Its +structure mimics a programmable logic array (PLA). Output port ``\Y`` is the sum +of products of the bits of the input port ``\A`` as defined by parameter +``\TABLE``. ``\A`` is ``\WIDTH`` bits wide. The number of products in the sum is +set by parameter ``\DEPTH``, and each product has two bits for each input bit - +for the presence of the unnegated and negated version of said input bit in the +product. Therefore the ``\TABLE`` parameter holds ``2 * \WIDTH * \DEPTH`` bits. + +For example: + +Let ``\WIDTH`` be 3. We would like to represent ``\Y =~\A[0] + \A[1]~\A[2]``. +There are 2 products to be summed, so ``\DEPTH`` shall be 2. + +.. code-block:: + + ~A[2]-----+ + A[2]----+| + ~A[1]---+|| + A[1]--+||| + ~A[0]-+|||| + A[0]+||||| + |||||| product formula + 010000 ~\A[0] + 001001 \A[1]~\A[2] + +So the value of ``\TABLE`` will become ``010000001001``. + +Any logic function with a single bit output can be represented with ``$sop`` but +may have variously minimized or ordered summands represented in the ``\TABLE`` +values. + +.. autocellgroup:: logic + :members: + :source: + :linenos: \ No newline at end of file diff --git a/docs/source/cell/word_mem.rst b/docs/source/cell/word_mem.rst new file mode 100644 index 000000000..434ddea3e --- /dev/null +++ b/docs/source/cell/word_mem.rst @@ -0,0 +1,281 @@ +.. role:: verilog(code) + :language: Verilog + +.. _sec:memcells: + +Memories +~~~~~~~~ + +Memories are either represented using ``RTLIL::Memory`` objects, `$memrd_v2`, +`$memwr_v2`, and `$meminit_v2` cells, or by `$mem_v2` cells alone. + +In the first alternative the ``RTLIL::Memory`` objects hold the general metadata +for the memory (bit width, size in number of words, etc.) and for each port a +`$memrd_v2` (read port) or `$memwr_v2` (write port) cell is created. Having +individual cells for read and write ports has the advantage that they can be +consolidated using resource sharing passes. In some cases this drastically +reduces the number of required ports on the memory cell. In this alternative, +memory initialization data is represented by `$meminit_v2` cells, which allow +delaying constant folding for initialization addresses and data until after the +frontend finishes. + +The `$memrd_v2` cells have a clock input ``CLK``, an enable input ``EN``, an +address input ``ADDR``, a data output ``DATA``, an asynchronous reset input +``ARST``, and a synchronous reset input ``SRST``. They also have the following +parameters: + +``MEMID`` + The name of the ``RTLIL::Memory`` object that is associated with this read + port. + +``ABITS`` + The number of address bits (width of the ``ADDR`` input port). + +``WIDTH`` + The number of data bits (width of the ``DATA`` output port). Note that this + may be a power-of-two multiple of the underlying memory's width -- such ports + are called wide ports and access an aligned group of cells at once. In this + case, the corresponding low bits of ``ADDR`` must be tied to 0. + +``CLK_ENABLE`` + When this parameter is non-zero, the clock is used. Otherwise this read port + is asynchronous and the ``CLK`` input is not used. + +``CLK_POLARITY`` + Clock is active on the positive edge if this parameter has the value ``1'b1`` + and on the negative edge if this parameter is ``1'b0``. + +``TRANSPARENCY_MASK`` + This parameter is a bitmask of write ports that this read port is transparent + with. The bits of this parameter are indexed by the write port's ``PORTID`` + parameter. Transparency can only be enabled between synchronous ports sharing + a clock domain. When transparency is enabled for a given port pair, a read + and write to the same address in the same cycle will return the new value. + Otherwise the old value is returned. + +``COLLISION_X_MASK`` + This parameter is a bitmask of write ports that have undefined collision + behavior with this port. The bits of this parameter are indexed by the write + port's ``PORTID`` parameter. This behavior can only be enabled between + synchronous ports sharing a clock domain. When undefined collision is enabled + for a given port pair, a read and write to the same address in the same cycle + will return the undefined (all-X) value.This option is exclusive (for a given + port pair) with the transparency option. + +``ARST_VALUE`` + Whenever the ``ARST`` input is asserted, the data output will be reset to + this value. Only used for synchronous ports. + +``SRST_VALUE`` + Whenever the ``SRST`` input is synchronously asserted, the data output will + be reset to this value. Only used for synchronous ports. + +``INIT_VALUE`` + The initial value of the data output, for synchronous ports. + +``CE_OVER_SRST`` + If this parameter is non-zero, the ``SRST`` input is only recognized when + ``EN`` is true. Otherwise, ``SRST`` is recognized regardless of ``EN``. + +The `$memwr_v2` cells have a clock input ``CLK``, an enable input ``EN`` (one +enable bit for each data bit), an address input ``ADDR`` and a data input +``DATA``. They also have the following parameters: + +``MEMID`` + The name of the ``RTLIL::Memory`` object that is associated with this write + port. + +``ABITS`` + The number of address bits (width of the ``ADDR`` input port). + +``WIDTH`` + The number of data bits (width of the ``DATA`` output port). Like with + `$memrd_v2` cells, the width is allowed to be any power-of-two multiple of + memory width, with the corresponding restriction on address. + +``CLK_ENABLE`` + When this parameter is non-zero, the clock is used. Otherwise this write port + is asynchronous and the ``CLK`` input is not used. + +``CLK_POLARITY`` + Clock is active on positive edge if this parameter has the value ``1'b1`` and + on the negative edge if this parameter is ``1'b0``. + +``PORTID`` + An identifier for this write port, used to index write port bit mask + parameters. + +``PRIORITY_MASK`` + This parameter is a bitmask of write ports that this write port has priority + over in case of writing to the same address. The bits of this parameter are + indexed by the other write port's ``PORTID`` parameter. Write ports can only + have priority over write ports with lower port ID. When two ports write to + the same address and neither has priority over the other, the result is + undefined. Priority can only be set between two synchronous ports sharing + the same clock domain. + +The `$meminit_v2` cells have an address input ``ADDR``, a data input ``DATA``, +with the width of the ``DATA`` port equal to ``WIDTH`` parameter times ``WORDS`` +parameter, and a bit enable mask input ``EN`` with width equal to ``WIDTH`` +parameter. All three of the inputs must resolve to a constant for synthesis to +succeed. + +``MEMID`` + The name of the ``RTLIL::Memory`` object that is associated with this + initialization cell. + +``ABITS`` + The number of address bits (width of the ``ADDR`` input port). + +``WIDTH`` + The number of data bits per memory location. + +``WORDS`` + The number of consecutive memory locations initialized by this cell. + +``PRIORITY`` + The cell with the higher integer value in this parameter wins an + initialization conflict. + +The HDL frontend models a memory using ``RTLIL::Memory`` objects and +asynchronous `$memrd_v2` and `$memwr_v2` cells. The `memory` pass (i.e. its +various sub-passes) migrates `$dff` cells into the `$memrd_v2` and `$memwr_v2` +cells making them synchronous, then converts them to a single `$mem_v2` cell and +(optionally) maps this cell type to `$dff` cells for the individual words and +multiplexer-based address decoders for the read and write interfaces. When the +last step is disabled or not possible, a `$mem_v2` cell is left in the design. + +The `$mem_v2` cell provides the following parameters: + +``MEMID`` + The name of the original ``RTLIL::Memory`` object that became this `$mem_v2` + cell. + +``SIZE`` + The number of words in the memory. + +``ABITS`` + The number of address bits. + +``WIDTH`` + The number of data bits per word. + +``INIT`` + The initial memory contents. + +``RD_PORTS`` + The number of read ports on this memory cell. + +``RD_WIDE_CONTINUATION`` + This parameter is ``RD_PORTS`` bits wide, containing a bitmask of "wide + continuation" read ports. Such ports are used to represent the extra data + bits of wide ports in the combined cell, and must have all control signals + identical with the preceding port, except for address, which must have the + proper sub-cell address encoded in the low bits. + +``RD_CLK_ENABLE`` + This parameter is ``RD_PORTS`` bits wide, containing a clock enable bit for + each read port. + +``RD_CLK_POLARITY`` + This parameter is ``RD_PORTS`` bits wide, containing a clock polarity bit for + each read port. + +``RD_TRANSPARENCY_MASK`` + This parameter is ``RD_PORTS*WR_PORTS`` bits wide, containing a concatenation + of all ``TRANSPARENCY_MASK`` values of the original `$memrd_v2` cells. + +``RD_COLLISION_X_MASK`` + This parameter is ``RD_PORTS*WR_PORTS`` bits wide, containing a concatenation + of all ``COLLISION_X_MASK`` values of the original `$memrd_v2` cells. + +``RD_CE_OVER_SRST`` + This parameter is ``RD_PORTS`` bits wide, determining relative synchronous + reset and enable priority for each read port. + +``RD_INIT_VALUE`` + This parameter is ``RD_PORTS*WIDTH`` bits wide, containing the initial value + for each synchronous read port. + +``RD_ARST_VALUE`` + This parameter is ``RD_PORTS*WIDTH`` bits wide, containing the asynchronous + reset value for each synchronous read port. + +``RD_SRST_VALUE`` + This parameter is ``RD_PORTS*WIDTH`` bits wide, containing the synchronous + reset value for each synchronous read port. + +``WR_PORTS`` + The number of write ports on this memory cell. + +``WR_WIDE_CONTINUATION`` + This parameter is ``WR_PORTS`` bits wide, containing a bitmask of "wide + continuation" write ports. + +``WR_CLK_ENABLE`` + This parameter is ``WR_PORTS`` bits wide, containing a clock enable bit for + each write port. + +``WR_CLK_POLARITY`` + This parameter is ``WR_PORTS`` bits wide, containing a clock polarity bit for + each write port. + +``WR_PRIORITY_MASK`` + This parameter is ``WR_PORTS*WR_PORTS`` bits wide, containing a concatenation + of all ``PRIORITY_MASK`` values of the original `$memwr_v2` cells. + +The `$mem_v2` cell has the following ports: + +``RD_CLK`` + This input is ``RD_PORTS`` bits wide, containing all clock signals for the + read ports. + +``RD_EN`` + This input is ``RD_PORTS`` bits wide, containing all enable signals for the + read ports. + +``RD_ADDR`` + This input is ``RD_PORTS*ABITS`` bits wide, containing all address signals + for the read ports. + +``RD_DATA`` + This output is ``RD_PORTS*WIDTH`` bits wide, containing all data signals for + the read ports. + +``RD_ARST`` + This input is ``RD_PORTS`` bits wide, containing all asynchronous reset + signals for the read ports. + +``RD_SRST`` + This input is ``RD_PORTS`` bits wide, containing all synchronous reset + signals for the read ports. + +``WR_CLK`` + This input is ``WR_PORTS`` bits wide, containing all clock signals for the + write ports. + +``WR_EN`` + This input is ``WR_PORTS*WIDTH`` bits wide, containing all enable signals for + the write ports. + +``WR_ADDR`` + This input is ``WR_PORTS*ABITS`` bits wide, containing all address signals + for the write ports. + +``WR_DATA`` + This input is ``WR_PORTS*WIDTH`` bits wide, containing all data signals for + the write ports. + +The `memory_collect` pass can be used to convert discrete `$memrd_v2`, +`$memwr_v2`, and `$meminit_v2` cells belonging to the same memory to a single +`$mem_v2` cell, whereas the `memory_unpack` pass performs the inverse operation. +The `memory_dff` pass can combine asynchronous memory ports that are fed by or +feeding registers into synchronous memory ports. The `memory_bram` pass can be +used to recognize `$mem_v2` cells that can be implemented with a block RAM +resource on an FPGA. The `memory_map` pass can be used to implement `$mem_v2` +cells as basic logic: word-wide DFFs and address decoders. + +.. autocellgroup:: mem + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_mux.rst b/docs/source/cell/word_mux.rst new file mode 100644 index 000000000..234d1016b --- /dev/null +++ b/docs/source/cell/word_mux.rst @@ -0,0 +1,47 @@ +.. role:: verilog(code) + :language: Verilog + +Multiplexers +------------ + +Multiplexers are generated by the Verilog HDL frontend for ``?:``-expressions. +Multiplexers are also generated by the proc pass to map the decision trees from +RTLIL::Process objects to logic. + +The simplest multiplexer cell type is `$mux`. Cells of this type have a +``WITDH`` parameter and data inputs ``A`` and ``B`` and a data output ``Y``, all +of the specified width. This cell also has a single bit control input ``S``. If +``S`` is 0 the value from the input ``A`` is sent to the output, if it is 1 the +value from the ``B`` input is sent to the output. So the `$mux` cell implements +the function :verilog:`Y = S ? B : A`. + +The `$pmux` cell is used to multiplex between many inputs using a one-hot select +signal. Cells of this type have a ``WIDTH`` and a ``S_WIDTH`` parameter and +inputs ``A``, ``B``, and ``S`` and an output ``Y``. The ``S`` input is +``S_WIDTH`` bits wide. The ``A`` input and the output are both ``WIDTH`` bits +wide and the ``B`` input is ``WIDTH*S_WIDTH`` bits wide. When all bits of ``S`` +are zero, the value from ``A`` input is sent to the output. If the :math:`n`\ +'th bit from ``S`` is set, the value :math:`n`\ 'th ``WIDTH`` bits wide slice of +the ``B`` input is sent to the output. When more than one bit from ``S`` is set +the output is undefined. Cells of this type are used to model "parallel cases" +(defined by using the ``parallel_case`` attribute, the ``unique`` or ``unique0`` +SystemVerilog keywords, or detected by an optimization). + +The `$tribuf` cell is used to implement tristate logic. Cells of this type have +a ``WIDTH`` parameter and inputs ``A`` and ``EN`` and an output ``Y``. The ``A`` +input and ``Y`` output are ``WIDTH`` bits wide, and the ``EN`` input is one bit +wide. When ``EN`` is 0, the output is not driven. When ``EN`` is 1, the value +from ``A`` input is sent to the ``Y`` output. Therefore, the `$tribuf` cell +implements the function :verilog:`Y = EN ? A : 'bz`. + +Behavioural code with cascaded if-then-else- and case-statements usually results +in trees of multiplexer cells. Many passes (from various optimizations to FSM +extraction) heavily depend on these multiplexer trees to understand dependencies +between signals. Therefore optimizations should not break these multiplexer +trees (e.g. by replacing a multiplexer between a calculated signal and a +constant zero with an `$and` gate). + +.. autocellgroup:: mux + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_reg.rst b/docs/source/cell/word_reg.rst new file mode 100644 index 000000000..25c82b8e6 --- /dev/null +++ b/docs/source/cell/word_reg.rst @@ -0,0 +1,124 @@ +.. role:: verilog(code) + :language: Verilog + +Registers +--------- + +SR-type latches are represented by `$sr` cells. These cells have input ports +``SET`` and ``CLR`` and an output port ``Q``. They have the following +parameters: + +``WIDTH`` + The width of inputs ``SET`` and ``CLR`` and output ``Q``. + +``SET_POLARITY`` + The set input bits are active-high if this parameter has the value ``1'b1`` + and active-low if this parameter is ``1'b0``. + +``CLR_POLARITY`` + The reset input bits are active-high if this parameter has the value ``1'b1`` + and active-low if this parameter is ``1'b0``. + +Both set and reset inputs have separate bits for every output bit. When both the +set and reset inputs of an `$sr` cell are active for a given bit index, the +reset input takes precedence. + +D-type flip-flops are represented by `$dff` cells. These cells have a clock port +``CLK``, an input port ``D`` and an output port ``Q``. The following parameters +are available for `$dff` cells: + +``WIDTH`` + The width of input ``D`` and output ``Q``. + +``CLK_POLARITY`` + Clock is active on the positive edge if this parameter has the value ``1'b1`` + and on the negative edge if this parameter is ``1'b0``. + +D-type flip-flops with asynchronous reset are represented by `$adff` cells. As +the `$dff` cells they have ``CLK``, ``D`` and ``Q`` ports. In addition they also +have a single-bit ``ARST`` input port for the reset pin and the following +additional two parameters: + +``ARST_POLARITY`` + The asynchronous reset is active-high if this parameter has the value + ``1'b1`` and active-low if this parameter is ``1'b0``. + +``ARST_VALUE`` + The state of ``Q`` will be set to this value when the reset is active. + +Usually these cells are generated by the `proc` pass using the information in +the designs RTLIL::Process objects. + +D-type flip-flops with synchronous reset are represented by `$sdff` cells. As +the `$dff` cells they have ``CLK``, ``D`` and ``Q`` ports. In addition they also +have a single-bit ``SRST`` input port for the reset pin and the following +additional two parameters: + +``SRST_POLARITY`` + The synchronous reset is active-high if this parameter has the value ``1'b1`` + and active-low if this parameter is ``1'b0``. + +``SRST_VALUE`` + The state of ``Q`` will be set to this value when the reset is active. + +Note that the `$adff` and `$sdff` cells can only be used when the reset value is +constant. + +D-type flip-flops with asynchronous load are represented by `$aldff` cells. As +the `$dff` cells they have ``CLK``, ``D`` and ``Q`` ports. In addition they also +have a single-bit ``ALOAD`` input port for the async load enable pin, a ``AD`` +input port with the same width as data for the async load data, and the +following additional parameter: + +``ALOAD_POLARITY`` + The asynchronous load is active-high if this parameter has the value ``1'b1`` + and active-low if this parameter is ``1'b0``. + +D-type flip-flops with asynchronous set and reset are represented by `$dffsr` +cells. As the `$dff` cells they have ``CLK``, ``D`` and ``Q`` ports. In addition +they also have multi-bit ``SET`` and ``CLR`` input ports and the corresponding +polarity parameters, like `$sr` cells. + +D-type flip-flops with enable are represented by `$dffe`, `$adffe`, `$aldffe`, +`$dffsre`, `$sdffe`, and `$sdffce` cells, which are enhanced variants of `$dff`, +`$adff`, `$aldff`, `$dffsr`, `$sdff` (with reset over enable) and `$sdff` (with +enable over reset) cells, respectively. They have the same ports and parameters +as their base cell. In addition they also have a single-bit ``EN`` input port +for the enable pin and the following parameter: + +``EN_POLARITY`` + The enable input is active-high if this parameter has the value ``1'b1`` and + active-low if this parameter is ``1'b0``. + +D-type latches are represented by `$dlatch` cells. These cells have an enable +port ``EN``, an input port ``D``, and an output port ``Q``. The following +parameters are available for `$dlatch` cells: + +``WIDTH`` + The width of input ``D`` and output ``Q``. + +``EN_POLARITY`` + The enable input is active-high if this parameter has the value ``1'b1`` and + active-low if this parameter is ``1'b0``. + +The latch is transparent when the ``EN`` input is active. + +D-type latches with reset are represented by `$adlatch` cells. In addition to +`$dlatch` ports and parameters, they also have a single-bit ``ARST`` input port +for the reset pin and the following additional parameters: + +``ARST_POLARITY`` + The asynchronous reset is active-high if this parameter has the value + ``1'b1`` and active-low if this parameter is ``1'b0``. + +``ARST_VALUE`` + The state of ``Q`` will be set to this value when the reset is active. + +D-type latches with set and reset are represented by `$dlatchsr` cells. In +addition to `$dlatch` ports and parameters, they also have multi-bit ``SET`` and +``CLR`` input ports and the corresponding polarity parameters, like `$sr` cells. + +.. autocellgroup:: reg + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_spec.rst b/docs/source/cell/word_spec.rst new file mode 100644 index 000000000..b5ce967d0 --- /dev/null +++ b/docs/source/cell/word_spec.rst @@ -0,0 +1,9 @@ +Specify rules +------------- + +.. todo:: `$specify2`, `$specify3`, and `$specrule` cells. + +.. autocellgroup:: spec + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_unary.rst b/docs/source/cell/word_unary.rst new file mode 100644 index 000000000..1243ef60c --- /dev/null +++ b/docs/source/cell/word_unary.rst @@ -0,0 +1,50 @@ +.. role:: verilog(code) + :language: Verilog + +Unary operators +--------------- + +All unary RTL cells have one input port ``A`` and one output port ``Y``. They +also have the following parameters: + +``A_SIGNED`` + Set to a non-zero value if the input ``A`` is signed and therefore should be + sign-extended when needed. + +``A_WIDTH`` + The width of the input port ``A``. + +``Y_WIDTH`` + The width of the output port ``Y``. + +.. table:: Cell types for unary operators with their corresponding Verilog expressions. + + ================== ============== + Verilog Cell Type + ================== ============== + :verilog:`Y = ~A` `$not` + :verilog:`Y = +A` `$pos` + :verilog:`Y = -A` `$neg` + :verilog:`Y = &A` `$reduce_and` + :verilog:`Y = |A` `$reduce_or` + :verilog:`Y = ^A` `$reduce_xor` + :verilog:`Y = ~^A` `$reduce_xnor` + :verilog:`Y = |A` `$reduce_bool` + :verilog:`Y = !A` `$logic_not` + ================== ============== + +For the unary cells that output a logical value (`$reduce_and`, `$reduce_or`, +`$reduce_xor`, `$reduce_xnor`, `$reduce_bool`, `$logic_not`), when the +``Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and only +the least significant bit varies. + +Note that `$reduce_or` and `$reduce_bool` generally represent the same logic +function. But the `read_verilog` frontend will generate them in different +situations. A `$reduce_or` cell is generated when the prefix ``|`` operator is +being used. A `$reduce_bool` cell is generated when a bit vector is used as a +condition in an ``if``-statement or ``?:``-expression. + +.. autocellgroup:: unary + :members: + :source: + :linenos: diff --git a/docs/source/cell/word_wire.rst b/docs/source/cell/word_wire.rst new file mode 100644 index 000000000..0434cceae --- /dev/null +++ b/docs/source/cell/word_wire.rst @@ -0,0 +1,9 @@ +Wire cells +------------------------- + +.. todo:: Add information about `$slice` and `$concat` cells. + +.. autocellgroup:: wire + :members: + :source: + :linenos: diff --git a/docs/source/cell_index.rst b/docs/source/cell_index.rst new file mode 100644 index 000000000..2d64db95e --- /dev/null +++ b/docs/source/cell_index.rst @@ -0,0 +1,15 @@ +Internal cell library +===================== + +The intermediate language used by Yosys (RTLIL) represents logic and memory with +a series of cells. This section provides details for those cells, breaking them +down into two major categories: coarse-grain word-level cells; and fine-grain +gate-level cells. An additional section contains a list of properties which may +be shared across multiple cells. + +.. toctree:: + :maxdepth: 2 + + /cell/index_word + /cell/index_gate + /cell/properties diff --git a/docs/source/code_examples/.gitignore b/docs/source/code_examples/.gitignore index b4a858a01..0eca4be80 100644 --- a/docs/source/code_examples/.gitignore +++ b/docs/source/code_examples/.gitignore @@ -1,2 +1,5 @@ *.dot *.pdf +*.out +*.log +*.stat diff --git a/docs/source/code_examples/extensions/Makefile b/docs/source/code_examples/extensions/Makefile index 8b5fa106a..74b547a20 100644 --- a/docs/source/code_examples/extensions/Makefile +++ b/docs/source/code_examples/extensions/Makefile @@ -2,9 +2,10 @@ PROGRAM_PREFIX := YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys -.PHONY: all dots -all: dots test0.log test1.log test2.log -dots: test1.dot +.PHONY: all dots examples +all: dots examples +dots: test1.dot my_cmd.so +examples: test0.log test1.log test2.log my_cmd.so CXXFLAGS=$(shell $(YOSYS)-config --cxxflags) DATDIR=$(shell $(YOSYS)-config --datdir) diff --git a/docs/source/code_examples/extensions/my_cmd.cc b/docs/source/code_examples/extensions/my_cmd.cc index 36ddbe175..e6660469c 100644 --- a/docs/source/code_examples/extensions/my_cmd.cc +++ b/docs/source/code_examples/extensions/my_cmd.cc @@ -51,10 +51,10 @@ struct Test2Pass : public Pass { Test2Pass() : Pass("test2", "demonstrating sigmap on test module") { } void execute(std::vector, RTLIL::Design *design) override { - if (design->selection_stack.back().empty()) + if (design->selection().empty()) log_cmd_error("This command can't operator on an empty selection!\n"); - RTLIL::Module *module = design->modules_.at("\\test"); + RTLIL::Module *module = design->module("\\test"); RTLIL::SigSpec a(module->wire("\\a")), x(module->wire("\\x")), y(module->wire("\\y")); log("%d %d %d\n", a == x, x == y, y == a); // will print "0 0 0" diff --git a/docs/source/code_examples/fifo/.gitignore b/docs/source/code_examples/fifo/.gitignore new file mode 100644 index 000000000..b858bebc6 --- /dev/null +++ b/docs/source/code_examples/fifo/.gitignore @@ -0,0 +1,2 @@ +*.out +*.stat diff --git a/docs/source/code_examples/fifo/Makefile b/docs/source/code_examples/fifo/Makefile index 0a1186a62..4836dac06 100644 --- a/docs/source/code_examples/fifo/Makefile +++ b/docs/source/code_examples/fifo/Makefile @@ -10,8 +10,10 @@ MAPDOT_NAMES += rdata_map_ffs rdata_map_luts rdata_map_cells DOTS := $(addsuffix .dot,$(DOT_NAMES)) MAPDOTS := $(addsuffix .dot,$(MAPDOT_NAMES)) -all: dots fifo.out fifo.stat +.PHONY: all dots examples +all: dots examples dots: $(DOTS) $(MAPDOTS) +examples: fifo.out fifo.stat $(DOTS) fifo.out: fifo.v fifo.ys $(YOSYS) fifo.ys -l fifo.out -Q -T @@ -22,3 +24,4 @@ $(MAPDOTS) fifo.stat: fifo.v fifo_map.ys .PHONY: clean clean: rm -f *.dot + rm -f fifo.out fifo.stat diff --git a/docs/source/code_examples/fifo/fifo.out b/docs/source/code_examples/fifo/fifo.out deleted file mode 100644 index ac132ee6c..000000000 --- a/docs/source/code_examples/fifo/fifo.out +++ /dev/null @@ -1,425 +0,0 @@ - --- Executing script file `fifo.ys' -- -$ yosys fifo.v - --- Parsing `fifo.v' using frontend ` -vlog2k' -- - -1. Executing Verilog-2005 frontend: fifo.v -Parsing Verilog input from `fifo.v' to AST representation. -Storing AST representation for module `$abstract\addr_gen'. -Storing AST representation for module `$abstract\fifo'. -Successfully finished Verilog frontend. -echo on - -yosys> hierarchy -top addr_gen - -2. Executing HIERARCHY pass (managing design hierarchy). - -3. Executing AST frontend in derive mode using pre-parsed AST for module `\addr_gen'. -Generating RTLIL representation for module `\addr_gen'. - -3.1. Analyzing design hierarchy.. -Top module: \addr_gen - -3.2. Analyzing design hierarchy.. -Top module: \addr_gen -Removing unused module `$abstract\fifo'. -Removing unused module `$abstract\addr_gen'. -Removed 2 unused modules. - -yosys> select -module addr_gen - -yosys [addr_gen]> select -list -addr_gen -addr_gen/$1\addr[7:0] -addr_gen/$add$fifo.v:19$3_Y -addr_gen/$eq$fifo.v:16$2_Y -addr_gen/$0\addr[7:0] -addr_gen/addr -addr_gen/rst -addr_gen/clk -addr_gen/en -addr_gen/$add$fifo.v:19$3 -addr_gen/$eq$fifo.v:16$2 -addr_gen/$proc$fifo.v:0$4 -addr_gen/$proc$fifo.v:12$1 - -yosys [addr_gen]> select t:* - -yosys [addr_gen]*> select -list -addr_gen/$add$fifo.v:19$3 -addr_gen/$eq$fifo.v:16$2 - -yosys [addr_gen]*> select -set new_cells % - -yosys [addr_gen]*> select -clear - -yosys> show -format dot -prefix addr_gen_show addr_gen - -4. Generating Graphviz representation of design. -Writing dot description to `addr_gen_show.dot'. -Dumping module addr_gen to page 1. - -yosys> show -format dot -prefix new_cells_show -notitle @new_cells - -5. Generating Graphviz representation of design. -Writing dot description to `new_cells_show.dot'. -Dumping selected parts of module addr_gen to page 1. - -yosys> show -color maroon3 @new_cells -color cornflowerblue p:* -notitle -format dot -prefix addr_gen_hier - -6. Generating Graphviz representation of design. -Writing dot description to `addr_gen_hier.dot'. -Dumping module addr_gen to page 1. - -yosys> proc -noopt - -7. Executing PROC pass (convert processes to netlists). - -yosys> proc_clean - -7.1. Executing PROC_CLEAN pass (remove empty switches from decision trees). -Cleaned up 0 empty switches. - -yosys> proc_rmdead - -7.2. Executing PROC_RMDEAD pass (remove dead branches from decision trees). -Marked 2 switch rules as full_case in process $proc$fifo.v:12$1 in module addr_gen. -Removed a total of 0 dead cases. - -yosys> proc_prune - -7.3. Executing PROC_PRUNE pass (remove redundant assignments in processes). -Removed 0 redundant assignments. -Promoted 1 assignment to connection. - -yosys> proc_init - -7.4. Executing PROC_INIT pass (extract init attributes). -Found init rule in `\addr_gen.$proc$fifo.v:0$4'. - Set init value: \addr = 8'00000000 - -yosys> proc_arst - -7.5. Executing PROC_ARST pass (detect async resets in processes). -Found async reset \rst in `\addr_gen.$proc$fifo.v:12$1'. - -yosys> proc_rom - -7.6. Executing PROC_ROM pass (convert switches to ROMs). -Converted 0 switches. - - -yosys> proc_mux - -7.7. Executing PROC_MUX pass (convert decision trees to multiplexers). -Creating decoders for process `\addr_gen.$proc$fifo.v:0$4'. -Creating decoders for process `\addr_gen.$proc$fifo.v:12$1'. - 1/1: $0\addr[7:0] - -yosys> proc_dlatch - -7.8. Executing PROC_DLATCH pass (convert process syncs to latches). - -yosys> proc_dff - -7.9. Executing PROC_DFF pass (convert process syncs to FFs). -Creating register for signal `\addr_gen.\addr' using process `\addr_gen.$proc$fifo.v:12$1'. - created $adff cell `$procdff$10' with positive edge clock and positive level reset. - -yosys> proc_memwr - -7.10. Executing PROC_MEMWR pass (convert process memory writes to cells). - -yosys> proc_clean - -7.11. Executing PROC_CLEAN pass (remove empty switches from decision trees). -Removing empty process `addr_gen.$proc$fifo.v:0$4'. -Found and cleaned up 2 empty switches in `\addr_gen.$proc$fifo.v:12$1'. -Removing empty process `addr_gen.$proc$fifo.v:12$1'. -Cleaned up 2 empty switches. - -yosys> select -set new_cells t:$mux t:*dff - -yosys> show -color maroon3 @new_cells -notitle -format dot -prefix addr_gen_proc - -8. Generating Graphviz representation of design. -Writing dot description to `addr_gen_proc.dot'. -Dumping module addr_gen to page 1. - -yosys> opt_expr - -9. Executing OPT_EXPR pass (perform const folding). -Optimizing module addr_gen. - -yosys> clean -Removed 0 unused cells and 4 unused wires. - -yosys> select -set new_cells t:$eq - -yosys> show -color cornflowerblue @new_cells -notitle -format dot -prefix addr_gen_clean - -10. Generating Graphviz representation of design. -Writing dot description to `addr_gen_clean.dot'. -Dumping module addr_gen to page 1. - -yosys> design -reset - -yosys> read_verilog fifo.v - -11. Executing Verilog-2005 frontend: fifo.v -Parsing Verilog input from `fifo.v' to AST representation. -Generating RTLIL representation for module `\addr_gen'. -Generating RTLIL representation for module `\fifo'. -Successfully finished Verilog frontend. - -yosys> hierarchy -check -top fifo - -12. Executing HIERARCHY pass (managing design hierarchy). - -12.1. Analyzing design hierarchy.. -Top module: \fifo -Used module: \addr_gen -Parameter \MAX_DATA = 256 - -12.2. Executing AST frontend in derive mode using pre-parsed AST for module `\addr_gen'. -Parameter \MAX_DATA = 256 -Generating RTLIL representation for module `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000'. -Parameter \MAX_DATA = 256 -Found cached RTLIL representation for module `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000'. - -12.3. Analyzing design hierarchy.. -Top module: \fifo -Used module: $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000 - -12.4. Analyzing design hierarchy.. -Top module: \fifo -Used module: $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000 -Removing unused module `\addr_gen'. -Removed 1 unused modules. - -yosys> proc - -13. Executing PROC pass (convert processes to netlists). - -yosys> proc_clean - -13.1. Executing PROC_CLEAN pass (remove empty switches from decision trees). -Cleaned up 0 empty switches. - -yosys> proc_rmdead - -13.2. Executing PROC_RMDEAD pass (remove dead branches from decision trees). -Marked 2 switch rules as full_case in process $proc$fifo.v:62$24 in module fifo. -Marked 1 switch rules as full_case in process $proc$fifo.v:36$16 in module fifo. -Marked 2 switch rules as full_case in process $proc$fifo.v:12$32 in module $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000. -Removed a total of 0 dead cases. - -yosys> proc_prune - -13.3. Executing PROC_PRUNE pass (remove redundant assignments in processes). -Removed 0 redundant assignments. -Promoted 6 assignments to connections. - -yosys> proc_init - -13.4. Executing PROC_INIT pass (extract init attributes). -Found init rule in `\fifo.$proc$fifo.v:0$31'. - Set init value: \count = 9'000000000 -Found init rule in `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:0$35'. - Set init value: \addr = 8'00000000 - -yosys> proc_arst - -13.5. Executing PROC_ARST pass (detect async resets in processes). -Found async reset \rst in `\fifo.$proc$fifo.v:62$24'. -Found async reset \rst in `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'. - -yosys> proc_rom - -13.6. Executing PROC_ROM pass (convert switches to ROMs). -Converted 0 switches. - - -yosys> proc_mux - -13.7. Executing PROC_MUX pass (convert decision trees to multiplexers). -Creating decoders for process `\fifo.$proc$fifo.v:0$31'. -Creating decoders for process `\fifo.$proc$fifo.v:62$24'. - 1/1: $0\count[8:0] -Creating decoders for process `\fifo.$proc$fifo.v:36$16'. - 1/3: $1$memwr$\data$fifo.v:38$15_EN[7:0]$22 - 2/3: $1$memwr$\data$fifo.v:38$15_DATA[7:0]$21 - 3/3: $1$memwr$\data$fifo.v:38$15_ADDR[7:0]$20 -Creating decoders for process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:0$35'. -Creating decoders for process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'. - 1/1: $0\addr[7:0] - -yosys> proc_dlatch - -13.8. Executing PROC_DLATCH pass (convert process syncs to latches). - -yosys> proc_dff - -13.9. Executing PROC_DFF pass (convert process syncs to FFs). -Creating register for signal `\fifo.\count' using process `\fifo.$proc$fifo.v:62$24'. - created $adff cell `$procdff$55' with positive edge clock and positive level reset. -Creating register for signal `\fifo.\rdata' using process `\fifo.$proc$fifo.v:36$16'. - created $dff cell `$procdff$56' with positive edge clock. -Creating register for signal `\fifo.$memwr$\data$fifo.v:38$15_ADDR' using process `\fifo.$proc$fifo.v:36$16'. - created $dff cell `$procdff$57' with positive edge clock. -Creating register for signal `\fifo.$memwr$\data$fifo.v:38$15_DATA' using process `\fifo.$proc$fifo.v:36$16'. - created $dff cell `$procdff$58' with positive edge clock. -Creating register for signal `\fifo.$memwr$\data$fifo.v:38$15_EN' using process `\fifo.$proc$fifo.v:36$16'. - created $dff cell `$procdff$59' with positive edge clock. -Creating register for signal `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.\addr' using process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'. - created $adff cell `$procdff$60' with positive edge clock and positive level reset. - -yosys> proc_memwr - -13.10. Executing PROC_MEMWR pass (convert process memory writes to cells). - -yosys> proc_clean - -13.11. Executing PROC_CLEAN pass (remove empty switches from decision trees). -Removing empty process `fifo.$proc$fifo.v:0$31'. -Found and cleaned up 2 empty switches in `\fifo.$proc$fifo.v:62$24'. -Removing empty process `fifo.$proc$fifo.v:62$24'. -Found and cleaned up 1 empty switch in `\fifo.$proc$fifo.v:36$16'. -Removing empty process `fifo.$proc$fifo.v:36$16'. -Removing empty process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:0$35'. -Found and cleaned up 2 empty switches in `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'. -Removing empty process `$paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000.$proc$fifo.v:12$32'. -Cleaned up 5 empty switches. - -yosys> opt_expr -keepdc - -13.12. Executing OPT_EXPR pass (perform const folding). -Optimizing module fifo. -Optimizing module $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000. - -yosys> select -set new_cells t:$memrd - -yosys> show -color maroon3 c:fifo_reader -color cornflowerblue @new_cells -notitle -format dot -prefix rdata_proc o:rdata %ci* - -14. Generating Graphviz representation of design. -Writing dot description to `rdata_proc.dot'. -Dumping selected parts of module fifo to page 1. - -yosys> flatten - -15. Executing FLATTEN pass (flatten design). -Deleting now unused module $paramod\addr_gen\MAX_DATA=s32'00000000000000000000000100000000. - - -yosys> clean -Removed 3 unused cells and 25 unused wires. - -yosys> select -set rdata_path o:rdata %ci* - -yosys> select -set new_cells @rdata_path o:rdata %ci3 %d i:* %d - -yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_flat @rdata_path - -16. Generating Graphviz representation of design. -Writing dot description to `rdata_flat.dot'. -Dumping selected parts of module fifo to page 1. - -yosys> opt_dff - -17. Executing OPT_DFF pass (perform DFF optimizations). -Adding EN signal on $procdff$55 ($adff) from module fifo (D = $0\count[8:0], Q = \count). -Adding EN signal on $flatten\fifo_writer.$procdff$60 ($adff) from module fifo (D = $flatten\fifo_writer.$procmux$51_Y, Q = \fifo_writer.addr). -Adding EN signal on $flatten\fifo_reader.$procdff$60 ($adff) from module fifo (D = $flatten\fifo_reader.$procmux$51_Y, Q = \fifo_reader.addr). - -yosys> select -set new_cells t:$adffe - -yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_adffe o:rdata %ci* - -18. Generating Graphviz representation of design. -Writing dot description to `rdata_adffe.dot'. -Dumping selected parts of module fifo to page 1. - -yosys> wreduce - -19. Executing WREDUCE pass (reducing word size of cells). -Removed top 31 bits (of 32) from port B of cell fifo.$add$fifo.v:66$27 ($add). -Removed top 23 bits (of 32) from port Y of cell fifo.$add$fifo.v:66$27 ($add). -Removed top 31 bits (of 32) from port B of cell fifo.$sub$fifo.v:68$30 ($sub). -Removed top 23 bits (of 32) from port Y of cell fifo.$sub$fifo.v:68$30 ($sub). -Removed top 1 bits (of 2) from port B of cell fifo.$auto$opt_dff.cc:195:make_patterns_logic$66 ($ne). -Removed cell fifo.$flatten\fifo_writer.$procmux$53 ($mux). -Removed top 31 bits (of 32) from port B of cell fifo.$flatten\fifo_writer.$add$fifo.v:19$34 ($add). -Removed top 24 bits (of 32) from port Y of cell fifo.$flatten\fifo_writer.$add$fifo.v:19$34 ($add). -Removed cell fifo.$flatten\fifo_reader.$procmux$53 ($mux). -Removed top 31 bits (of 32) from port B of cell fifo.$flatten\fifo_reader.$add$fifo.v:19$34 ($add). -Removed top 24 bits (of 32) from port Y of cell fifo.$flatten\fifo_reader.$add$fifo.v:19$34 ($add). -Removed top 23 bits (of 32) from wire fifo.$add$fifo.v:66$27_Y. -Removed top 24 bits (of 32) from wire fifo.$flatten\fifo_reader.$add$fifo.v:19$34_Y. - -yosys> show -notitle -format dot -prefix rdata_wreduce o:rdata %ci* - -20. Generating Graphviz representation of design. -Writing dot description to `rdata_wreduce.dot'. -Dumping selected parts of module fifo to page 1. - -yosys> opt_clean - -21. Executing OPT_CLEAN pass (remove unused cells and wires). -Finding unused cells or wires in module \fifo.. -Removed 0 unused cells and 4 unused wires. - - -yosys> memory_dff - -22. Executing MEMORY_DFF pass (merging $dff cells to $memrd). -Checking read port `\data'[0] in module `\fifo': merging output FF to cell. - Write port 0: non-transparent. - -yosys> select -set new_cells t:$memrd_v2 - -yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_memrdv2 o:rdata %ci* - -23. Generating Graphviz representation of design. -Writing dot description to `rdata_memrdv2.dot'. -Dumping selected parts of module fifo to page 1. - -yosys> alumacc - -24. Executing ALUMACC pass (create $alu and $macc cells). -Extracting $alu and $macc cells in module fifo: - creating $macc model for $add$fifo.v:66$27 ($add). - creating $macc model for $flatten\fifo_reader.$add$fifo.v:19$34 ($add). - creating $macc model for $flatten\fifo_writer.$add$fifo.v:19$34 ($add). - creating $macc model for $sub$fifo.v:68$30 ($sub). - creating $alu model for $macc $sub$fifo.v:68$30. - creating $alu model for $macc $flatten\fifo_writer.$add$fifo.v:19$34. - creating $alu model for $macc $flatten\fifo_reader.$add$fifo.v:19$34. - creating $alu model for $macc $add$fifo.v:66$27. - creating $alu cell for $add$fifo.v:66$27: $auto$alumacc.cc:485:replace_alu$80 - creating $alu cell for $flatten\fifo_reader.$add$fifo.v:19$34: $auto$alumacc.cc:485:replace_alu$83 - creating $alu cell for $flatten\fifo_writer.$add$fifo.v:19$34: $auto$alumacc.cc:485:replace_alu$86 - creating $alu cell for $sub$fifo.v:68$30: $auto$alumacc.cc:485:replace_alu$89 - created 4 $alu and 0 $macc cells. - -yosys> select -set new_cells t:$alu t:$macc - -yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_alumacc o:rdata %ci* - -25. Generating Graphviz representation of design. -Writing dot description to `rdata_alumacc.dot'. -Dumping selected parts of module fifo to page 1. - -yosys> memory_collect - -26. Executing MEMORY_COLLECT pass (generating $mem cells). - -yosys> select -set new_cells t:$mem_v2 - -yosys> select -set rdata_path @new_cells %ci*:-$mem_v2[WR_DATA,WR_ADDR,WR_EN] @new_cells %co* %% - -yosys> show -color maroon3 @new_cells -notitle -format dot -prefix rdata_coarse @rdata_path - -27. Generating Graphviz representation of design. -Writing dot description to `rdata_coarse.dot'. -Dumping selected parts of module fifo to page 1. diff --git a/docs/source/code_examples/fifo/fifo.stat b/docs/source/code_examples/fifo/fifo.stat deleted file mode 100644 index 263c618e3..000000000 --- a/docs/source/code_examples/fifo/fifo.stat +++ /dev/null @@ -1,57 +0,0 @@ - -yosys> stat - -2. Printing statistics. - -=== fifo === - - Number of wires: 28 - Number of wire bits: 219 - Number of public wires: 9 - Number of public wire bits: 45 - Number of memories: 1 - Number of memory bits: 2048 - Number of processes: 3 - Number of cells: 9 - $add 1 - $logic_and 2 - $logic_not 2 - $memrd 1 - $sub 1 - addr_gen 2 - -=== addr_gen === - - Number of wires: 8 - Number of wire bits: 60 - Number of public wires: 4 - Number of public wire bits: 11 - Number of memories: 0 - Number of memory bits: 0 - Number of processes: 2 - Number of cells: 2 - $add 1 - $eq 1 - - -yosys> stat -top fifo - -17. Printing statistics. - -=== fifo === - - Number of wires: 94 - Number of wire bits: 260 - Number of public wires: 94 - Number of public wire bits: 260 - Number of memories: 0 - Number of memory bits: 0 - Number of processes: 0 - Number of cells: 138 - $scopeinfo 2 - SB_CARRY 26 - SB_DFF 26 - SB_DFFER 25 - SB_LUT4 58 - SB_RAM40_4K 1 - diff --git a/docs/source/code_examples/fifo/fifo.v b/docs/source/code_examples/fifo/fifo.v index 769dfafd4..86f292406 100644 --- a/docs/source/code_examples/fifo/fifo.v +++ b/docs/source/code_examples/fifo/fifo.v @@ -5,7 +5,7 @@ module addr_gen ) ( input en, clk, rst, output reg [AWIDTH-1:0] addr ); - initial addr <= 0; + initial addr = 0; // async reset // increment address when enabled @@ -13,7 +13,7 @@ module addr_gen if (rst) addr <= 0; else if (en) begin - if (addr == MAX_DATA-1) + if ({'0, addr} == MAX_DATA-1) addr <= 0; else addr <= addr + 1; @@ -57,7 +57,7 @@ module fifo ); // status signals - initial count <= 0; + initial count = 0; always @(posedge clk or posedge rst) begin if (rst) diff --git a/docs/source/code_examples/fifo/fifo.ys b/docs/source/code_examples/fifo/fifo.ys index 57a28e63e..e6b9bf69d 100644 --- a/docs/source/code_examples/fifo/fifo.ys +++ b/docs/source/code_examples/fifo/fifo.ys @@ -67,7 +67,7 @@ show -color maroon3 @new_cells -notitle -format dot -prefix rdata_memrdv2 o:rdat # ======================================================== alumacc -select -set new_cells t:$alu t:$macc +select -set new_cells t:$alu t:$macc_v2 show -color maroon3 @new_cells -notitle -format dot -prefix rdata_alumacc o:rdata %ci* # ======================================================== diff --git a/docs/source/code_examples/functional/dummy.cc b/docs/source/code_examples/functional/dummy.cc new file mode 100644 index 000000000..3d84b84ba --- /dev/null +++ b/docs/source/code_examples/functional/dummy.cc @@ -0,0 +1,44 @@ +#include "kernel/functional.h" +#include "kernel/yosys.h" + +USING_YOSYS_NAMESPACE +PRIVATE_NAMESPACE_BEGIN + +struct FunctionalDummyBackend : public Backend { + FunctionalDummyBackend() : Backend("functional_dummy", "dump generated Functional IR") {} + void execute(std::ostream *&f, std::string filename, std::vector args, RTLIL::Design *design) override + { + // backend pass boiler plate + log_header(design, "Executing dummy functional backend.\n"); + + size_t argidx = 1; + extra_args(f, filename, args, argidx, design); + + for (auto module : design->selected_modules()) + { + log("Processing module `%s`.\n", module->name.c_str()); + + // convert module to FunctionalIR + auto ir = Functional::IR::from_module(module); + *f << "module " << module->name.c_str() << "\n"; + + // write node functions + for (auto node : ir) + *f << " assign " << id2cstr(node.name()) + << " = " << node.to_string() << "\n"; + *f << "\n"; + + // write outputs and next state + for (auto output : ir.outputs()) + *f << " " << id2cstr(output->kind) + << " " << id2cstr(output->name) + << " = " << id2cstr(output->value().name()) << "\n"; + for (auto state : ir.states()) + *f << " " << id2cstr(state->kind) + << " " << id2cstr(state->name) + << " = " << id2cstr(state->next_value().name()) << "\n"; + } + } +} FunctionalDummyBackend; + +PRIVATE_NAMESPACE_END diff --git a/docs/source/code_examples/intro/Makefile b/docs/source/code_examples/intro/Makefile index 009c82c62..31df6b623 100644 --- a/docs/source/code_examples/intro/Makefile +++ b/docs/source/code_examples/intro/Makefile @@ -4,8 +4,10 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys DOTS = counter_00.dot counter_01.dot counter_02.dot counter_03.dot -all: dots +.PHONY: all dots examples +all: dots examples dots: $(DOTS) +examples: $(DOTS): counter.v counter.ys mycells.lib $(YOSYS) counter.ys diff --git a/docs/source/code_examples/macc/Makefile b/docs/source/code_examples/macc/Makefile index e93fe0657..f06c623a5 100644 --- a/docs/source/code_examples/macc/Makefile +++ b/docs/source/code_examples/macc/Makefile @@ -4,8 +4,10 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys DOTS = macc_simple_xmap.dot macc_xilinx_xmap.dot -all: dots +.PHONY: all dots examples +all: dots examples dots: $(DOTS) +examples: macc_simple_xmap.dot: macc_simple_*.v macc_simple_test.ys $(YOSYS) macc_simple_test.ys diff --git a/docs/source/code_examples/macro_commands/opt.ys b/docs/source/code_examples/macro_commands/opt.ys index cb883bc58..ebd938836 100644 --- a/docs/source/code_examples/macro_commands/opt.ys +++ b/docs/source/code_examples/macro_commands/opt.ys @@ -9,6 +9,7 @@ do opt_merge opt_share (-full only) opt_dff (except when called with -noff) + opt_hier (-hier only) opt_clean opt_expr while diff --git a/docs/source/code_examples/opt/Makefile b/docs/source/code_examples/opt/Makefile index 12c1c93b1..aa7962ca5 100644 --- a/docs/source/code_examples/opt/Makefile +++ b/docs/source/code_examples/opt/Makefile @@ -6,13 +6,13 @@ DOT_NAMES = opt_share opt_muxtree opt_merge opt_expr DOTS := $(addsuffix .dot,$(DOT_NAMES)) -all: dots +.PHONY: all dots examples +all: dots examples dots: $(DOTS) +examples: -%_full.dot: %.ys +%.dot: %.ys $(YOSYS) $< - -%.dot: %_full.dot gvpack -u -o $@ $*_full.dot .PHONY: clean diff --git a/docs/source/code_examples/scrambler/Makefile b/docs/source/code_examples/scrambler/Makefile index de475b8b1..a9b56f8d3 100644 --- a/docs/source/code_examples/scrambler/Makefile +++ b/docs/source/code_examples/scrambler/Makefile @@ -2,9 +2,10 @@ PROGRAM_PREFIX := YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys -.PHONY: all dots -all: dots +.PHONY: all dots examples +all: dots examples dots: scrambler_p01.dot scrambler_p02.dot +examples: scrambler_p01.dot scrambler_p02.dot: scrambler.ys scrambler.v $(YOSYS) scrambler.ys diff --git a/docs/source/code_examples/selections/Makefile b/docs/source/code_examples/selections/Makefile index bb506ff38..46a09060a 100644 --- a/docs/source/code_examples/selections/Makefile +++ b/docs/source/code_examples/selections/Makefile @@ -11,14 +11,15 @@ MEMDEMO_DOTS := $(addsuffix .dot,$(MEMDEMO)) SUBMOD = submod_00 submod_01 submod_02 submod_03 SUBMOD_DOTS := $(addsuffix .dot,$(SUBMOD)) -.PHONY: all dots -all: dots +.PHONY: all dots examples +all: dots examples dots: select.dot $(SUMPROD_DOTS) $(MEMDEMO_DOTS) $(SUBMOD_DOTS) +examples: sumprod.out select.dot: select.v select.ys $(YOSYS) select.ys -$(SUMPROD_DOTS): sumprod.v sumprod.ys +$(SUMPROD_DOTS) sumprod.out: sumprod.v sumprod.ys $(YOSYS) sumprod.ys $(MEMDEMO_DOTS): memdemo.v memdemo.ys @@ -30,3 +31,4 @@ $(SUBMOD_DOTS): memdemo.v submod.ys .PHONY: clean clean: rm -rf *.dot + rm -f sumprod.out diff --git a/docs/source/code_examples/selections/sumprod.out b/docs/source/code_examples/selections/sumprod.out deleted file mode 100644 index f7c259499..000000000 --- a/docs/source/code_examples/selections/sumprod.out +++ /dev/null @@ -1,38 +0,0 @@ - - - attribute \src "sumprod.v:4.21-4.25" - wire width 8 output 5 \prod - - attribute \src "sumprod.v:10.17-10.26" - cell $mul $mul$sumprod.v:10$4 - parameter \A_SIGNED 0 - parameter \A_WIDTH 8 - parameter \B_SIGNED 0 - parameter \B_WIDTH 8 - parameter \Y_WIDTH 8 - connect \A $mul$sumprod.v:10$3_Y - connect \B \c - connect \Y \prod - end - - - attribute \src "sumprod.v:10.17-10.22" - wire width 8 $mul$sumprod.v:10$3_Y - - attribute \src "sumprod.v:3.21-3.22" - wire width 8 input 3 \c - - attribute \src "sumprod.v:4.21-4.25" - wire width 8 output 5 \prod - - attribute \src "sumprod.v:10.17-10.26" - cell $mul $mul$sumprod.v:10$4 - parameter \A_SIGNED 0 - parameter \A_WIDTH 8 - parameter \B_SIGNED 0 - parameter \B_WIDTH 8 - parameter \Y_WIDTH 8 - connect \A $mul$sumprod.v:10$3_Y - connect \B \c - connect \Y \prod - end diff --git a/docs/source/code_examples/show/Makefile b/docs/source/code_examples/show/Makefile index 4b269a4ab..649691299 100644 --- a/docs/source/code_examples/show/Makefile +++ b/docs/source/code_examples/show/Makefile @@ -8,9 +8,10 @@ EXAMPLE_DOTS := $(addsuffix .dot,$(EXAMPLE)) CMOS = cmos_00 cmos_01 CMOS_DOTS := $(addsuffix .dot,$(CMOS)) -.PHONY: all dots -all: dots example.out +.PHONY: all dots examples +all: dots examples dots: splice.dot $(EXAMPLE_DOTS) $(CMOS_DOTS) +examples: example.out splice.dot: splice.v $(YOSYS) -p 'prep -top splice_demo; show -format dot -prefix splice' splice.v @@ -27,3 +28,4 @@ $(CMOS_DOTS): cmos.v cmos.ys .PHONY: clean clean: rm -rf *.dot + rm -f example.out diff --git a/docs/source/code_examples/show/example.out b/docs/source/code_examples/show/example.out deleted file mode 100644 index b8569e640..000000000 --- a/docs/source/code_examples/show/example.out +++ /dev/null @@ -1,54 +0,0 @@ - --- Executing script file `example_lscd.ys' -- - -1. Executing Verilog-2005 frontend: example.v -Parsing Verilog input from `example.v' to AST representation. -Generating RTLIL representation for module `\example'. -Successfully finished Verilog frontend. -echo on - -yosys> ls - -1 modules: - example - -yosys> cd example - -yosys [example]> ls - -8 wires: - $0\y[1:0] - $add$example.v:5$2_Y - $ternary$example.v:5$3_Y - a - b - c - clk - y - -2 cells: - $add$example.v:5$2 - $ternary$example.v:5$3 - -1 processes: - $proc$example.v:3$1 - -yosys [example]> dump $2 - - - attribute \src "example.v:5.22-5.27" - cell $add $add$example.v:5$2 - parameter \Y_WIDTH 2 - parameter \B_WIDTH 1 - parameter \A_WIDTH 1 - parameter \B_SIGNED 0 - parameter \A_SIGNED 0 - connect \Y $add$example.v:5$2_Y - connect \B \b - connect \A \a - end - -yosys [example]> cd .. - -yosys> echo off -echo off diff --git a/docs/source/code_examples/stubnets/Makefile b/docs/source/code_examples/stubnets/Makefile index ec501f006..17f700c88 100644 --- a/docs/source/code_examples/stubnets/Makefile +++ b/docs/source/code_examples/stubnets/Makefile @@ -1,6 +1,7 @@ -.PHONY: all dots -all: dots +.PHONY: all dots examples +all: dots examples dots: +examples: .PHONY: test test: stubnets.so diff --git a/docs/source/code_examples/synth_flow/Makefile b/docs/source/code_examples/synth_flow/Makefile index 7db1c12f4..0dd37ed4d 100644 --- a/docs/source/code_examples/synth_flow/Makefile +++ b/docs/source/code_examples/synth_flow/Makefile @@ -9,9 +9,10 @@ YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys DOTS = $(addsuffix .dot,$(DOT_TARGETS)) -.PHONY: all dots -all: dots +.PHONY: all dots examples +all: dots examples dots: $(DOTS) +examples: %.dot: %.v %.ys $(YOSYS) -p 'script $*.ys; show -notitle -prefix $* -format dot' diff --git a/docs/source/code_examples/techmap/Makefile b/docs/source/code_examples/techmap/Makefile index e900fea4c..6736b0f1d 100644 --- a/docs/source/code_examples/techmap/Makefile +++ b/docs/source/code_examples/techmap/Makefile @@ -2,9 +2,10 @@ PROGRAM_PREFIX := YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys -.PHONY: all dots -all: dots +.PHONY: all dots examples +all: dots examples dots: red_or3x1.dot sym_mul.dot mymul.dot mulshift.dot addshift.dot +examples: red_or3x1.dot: red_or3x1_* $(YOSYS) red_or3x1_test.ys diff --git a/docs/source/conf.py b/docs/source/conf.py index 4371b79f1..05dcb7d5f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,46 +1,51 @@ #!/usr/bin/env python3 +from pathlib import Path import sys import os project = 'YosysHQ Yosys' author = 'YosysHQ GmbH' -copyright ='2024 YosysHQ GmbH' -yosys_ver = "0.45" +copyright ='2025 YosysHQ GmbH' +yosys_ver = "0.55" # select HTML theme -html_theme = 'furo' -templates_path = ["_templates"] -html_logo = '_static/logo.png' -html_favicon = '_static/favico.png' -html_css_files = ['yosyshq.css', 'custom.css'] - -html_theme_options = { - "sidebar_hide_name": True, - - "light_css_variables": { - "color-brand-primary": "#d6368f", - "color-brand-content": "#4b72b8", - "color-api-name": "#8857a3", - "color-api-pre-name": "#4b72b8", - "color-link": "#8857a3", - }, - - "dark_css_variables": { - "color-brand-primary": "#e488bb", - "color-brand-content": "#98bdff", - "color-api-name": "#8857a3", - "color-api-pre-name": "#4b72b8", - "color-link": "#be95d5", - }, +html_theme = 'furo-ys' +html_css_files = ['custom.css'] +html_theme_options: dict[str] = { + "source_repository": "https://github.com/YosysHQ/yosys/", + "source_branch": "main", + "source_directory": "docs/source/", } +html_context: dict[str] = {} + +# try to fix the readthedocs detection +if os.getenv("READTHEDOCS"): + html_context.update({ + "READTHEDOCS": True, + "display_github": True, + "github_user": "YosysHQ", + "github_repo": "yosys", + "slug": "yosys", + }) + +# override source_branch if not main +git_slug = os.getenv("READTHEDOCS_VERSION_NAME") +if git_slug not in [None, "latest", "stable"]: + html_theme_options["source_branch"] = git_slug + +# edit only works on branches, not tags +if os.getenv("READTHEDOCS_VERSION_TYPE", "branch") != "branch": + html_theme_options["top_of_page_buttons"] = ["view"] # These folders are copied to the documentation's HTML output html_static_path = ['_static', "_images"] -# code blocks style -pygments_style = 'colorful' +# default to no highlight highlight_language = 'none' +# default single quotes to attempt auto reference, or fallback to code +default_role = 'autoref' + extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex'] if os.getenv("READTHEDOCS"): @@ -76,6 +81,9 @@ if os.getenv("READTHEDOCS"): else: release = yosys_ver todo_include_todos = False +elif os.getenv("YOSYS_DOCS_RELEASE") is not None: + release = yosys_ver + todo_include_todos = False else: release = yosys_ver todo_include_todos = True @@ -87,6 +95,9 @@ bibtex_bibfiles = ['literature.bib'] latex_elements = { 'releasename': 'Version', 'preamble': r''' +\pdfinfoomitdate 1 +\pdfsuppressptexinfo 1 +\pdftrailerid{} \usepackage{lmodern} \usepackage{comment} @@ -97,9 +108,19 @@ latex_elements = { sys.path += [os.path.dirname(__file__) + "/../"] extensions.append('util.cmdref') -def setup(sphinx): - from util.RtlilLexer import RtlilLexer - sphinx.add_lexer("RTLIL", RtlilLexer) +# use autodocs +extensions.append('sphinx.ext.autodoc') +extensions.append('util.cellref') +cells_json = Path(__file__).parent / 'generated' / 'cells.json' - from util.YoscryptLexer import YoscryptLexer - sphinx.add_lexer("yoscrypt", YoscryptLexer) \ No newline at end of file +from sphinx.application import Sphinx +def setup(app: Sphinx) -> None: + from util.RtlilLexer import RtlilLexer + app.add_lexer("RTLIL", RtlilLexer) + + try: + from furo_ys.lexers.YoscryptLexer import YoscryptLexer + app.add_lexer("yoscrypt", YoscryptLexer) + except ModuleNotFoundError: + from pygments.lexers.special import TextLexer + app.add_lexer("yoscrypt", TextLexer) diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst index ae0a9a366..e215586cc 100644 --- a/docs/source/getting_started/example_synth.rst +++ b/docs/source/getting_started/example_synth.rst @@ -2,13 +2,12 @@ Synthesis starter ----------------- This page will be a guided walkthrough of the prepackaged iCE40 FPGA synthesis -script - :cmd:ref:`synth_ice40`. We will take a simple design through each -step, looking at the commands being called and what they do to the design. While -:cmd:ref:`synth_ice40` is specific to the iCE40 platform, most of the operations -we will be discussing are common across the majority of FPGA synthesis scripts. -Thus, this document will provide a good foundational understanding of how -synthesis in Yosys is performed, regardless of the actual architecture being -used. +script - `synth_ice40`. We will take a simple design through each step, looking +at the commands being called and what they do to the design. While `synth_ice40` +is specific to the iCE40 platform, most of the operations we will be discussing +are common across the majority of FPGA synthesis scripts. Thus, this document +will provide a good foundational understanding of how synthesis in Yosys is +performed, regardless of the actual architecture being used. .. seealso:: Advanced usage docs for :doc:`/using_yosys/synthesis/synth` @@ -31,6 +30,14 @@ First, let's quickly look at the design we'll be synthesizing: .. todo:: fifo.v description +While the open source `read_verilog` frontend generally does a pretty good job +at processing valid Verilog input, it does not provide very good error handling +or reporting. Using an external tool such as `verilator`_ before running Yosys +is highly recommended. We can quickly check the Verilog syntax of our design by +calling ``verilator --lint-only fifo.v``. + +.. _verilator: https://www.veripool.org/verilator/ + Loading the design ~~~~~~~~~~~~~~~~~~ @@ -59,8 +66,8 @@ can run each of the commands individually for a better sense of how each part contributes to the flow. We will also start with just a single module; ``addr_gen``. -At the bottom of the :cmd:ref:`help` output for -:cmd:ref:`synth_ice40` is the complete list of commands called by this script. +At the bottom of the `help` output for +`synth_ice40` is the complete list of commands called by this script. Let's start with the section labeled ``begin``: .. literalinclude:: /cmd/synth_ice40.rst @@ -105,10 +112,10 @@ Since we're just getting started, let's instead begin with :yoscrypt:`hierarchy .. note:: - :cmd:ref:`hierarchy` should always be the first command after the design has - been read. By specifying the top module, :cmd:ref:`hierarchy` will also set - the ``(* top *)`` attribute on it. This is used by other commands that need - to know which module is the top. + `hierarchy` should always be the first command after the design has been + read. By specifying the top module, `hierarchy` will also set the ``(* top + *)`` attribute on it. This is used by other commands that need to know which + module is the top. .. use doscon for a console-like display that supports the `yosys> [command]` format. @@ -125,24 +132,24 @@ Our ``addr_gen`` circuit now looks like this: :class: width-helper invert-helper :name: addr_gen_hier - ``addr_gen`` module after :cmd:ref:`hierarchy` + ``addr_gen`` module after `hierarchy` Simple operations like ``addr + 1`` and ``addr == MAX_DATA-1`` can be extracted from our ``always @`` block in :ref:`addr_gen-v`. This gives us the highlighted -``$add`` and ``$eq`` cells we see. But control logic (like the ``if .. else``) -and memory elements (like the ``addr <= 0``) are not so straightforward. These -get put into "processes", shown in the schematic as ``PROC``. Note how the -second line refers to the line numbers of the start/end of the corresponding -``always @`` block. In the case of an ``initial`` block, we instead see the -``PROC`` referring to line 0. +`$add` and `$eq` cells we see. But control logic (like the ``if .. else``) and +memory elements (like the ``addr <= 0``) are not so straightforward. These get +put into "processes", shown in the schematic as ``PROC``. Note how the second +line refers to the line numbers of the start/end of the corresponding ``always +@`` block. In the case of an ``initial`` block, we instead see the ``PROC`` +referring to line 0. -To handle these, let us now introduce the next command: :doc:`/cmd/proc`. -:cmd:ref:`proc` is a macro command like :cmd:ref:`synth_ice40`. Rather than -modifying the design directly, it instead calls a series of other commands. In -the case of :cmd:ref:`proc`, these sub-commands work to convert the behavioral -logic of processes into multiplexers and registers. Let's see what happens when -we run it. For now, we will call :yoscrypt:`proc -noopt` to prevent some -automatic optimizations which would normally happen. +To handle these, let us now introduce the next command: :doc:`/cmd/proc`. `proc` +is a macro command like `synth_ice40`. Rather than modifying the design +directly, it instead calls a series of other commands. In the case of `proc`, +these sub-commands work to convert the behavioral logic of processes into +multiplexers and registers. Let's see what happens when we run it. For now, we +will call :yoscrypt:`proc -noopt` to prevent some automatic optimizations which +would normally happen. .. figure:: /_images/code_examples/fifo/addr_gen_proc.* :class: width-helper invert-helper @@ -151,19 +158,18 @@ automatic optimizations which would normally happen. ``addr_gen`` module after :yoscrypt:`proc -noopt` There are now a few new cells from our ``always @``, which have been -highlighted. The ``if`` statements are now modeled with ``$mux`` cells, while -the register uses an ``$adff`` cell. If we look at the terminal output we can -also see all of the different ``proc_*`` commands being called. We will look at -each of these in more detail in :doc:`/using_yosys/synthesis/proc`. +highlighted. The ``if`` statements are now modeled with `$mux` cells, while the +register uses an `$adff` cell. If we look at the terminal output we can also +see all of the different ``proc_*`` commands being called. We will look at each +of these in more detail in :doc:`/using_yosys/synthesis/proc`. Notice how in the top left of :ref:`addr_gen_proc` we have a floating wire, generated from the initial assignment of 0 to the ``addr`` wire. However, this initial assignment is not synthesizable, so this will need to be cleaned up before we can generate the physical hardware. We can do this now by calling -:cmd:ref:`clean`. We're also going to call :cmd:ref:`opt_expr` now, which would -normally be called at the end of :cmd:ref:`proc`. We can call both commands at -the same time by separating them with a colon and space: :yoscrypt:`opt_expr; -clean`. +`clean`. We're also going to call `opt_expr` now, which would normally be +called at the end of `proc`. We can call both commands at the same time by +separating them with a colon and space: :yoscrypt:`opt_expr; clean`. .. figure:: /_images/code_examples/fifo/addr_gen_clean.* :class: width-helper invert-helper @@ -171,24 +177,24 @@ clean`. ``addr_gen`` module after :yoscrypt:`opt_expr; clean` -You may also notice that the highlighted ``$eq`` cell input of ``255`` has -changed to ``8'11111111``. Constant values are presented in the format +You may also notice that the highlighted `$eq` cell input of ``255`` has changed +to ``8'11111111``. Constant values are presented in the format ``'``, with 32-bit values instead using the decimal number. This indicates that the constant input has been reduced from 32-bit wide to -8-bit wide. This is a side-effect of running :cmd:ref:`opt_expr`, which -performs constant folding and simple expression rewriting. For more on why -this happens, refer to :doc:`/using_yosys/synthesis/opt` and the :ref:`section -on opt_expr `. +8-bit wide. This is a side-effect of running `opt_expr`, which performs +constant folding and simple expression rewriting. For more on why this +happens, refer to :doc:`/using_yosys/synthesis/opt` and the :ref:`section on +opt_expr `. .. note:: :doc:`/cmd/clean` can also be called with two semicolons after any command, for example we could have called :yoscrypt:`opt_expr;;` instead of :yoscrypt:`opt_expr; clean`. You may notice some scripts will end each line - with ``;;``. It is beneficial to run :cmd:ref:`clean` before inspecting - intermediate products to remove disconnected parts of the circuit which have - been left over, and in some cases can reduce the processing required in - subsequent commands. + with ``;;``. It is beneficial to run `clean` before inspecting intermediate + products to remove disconnected parts of the circuit which have been left + over, and in some cases can reduce the processing required in subsequent + commands. .. todo:: consider a brief glossary for terms like adff @@ -202,8 +208,8 @@ The full example Let's now go back and check on our full design by using :yoscrypt:`hierarchy -check -top fifo`. By passing the ``-check`` option there we are also telling -the :cmd:ref:`hierarchy` command that if the design includes any non-blackbox -modules without an implementation it should return an error. +the `hierarchy` command that if the design includes any non-blackbox modules +without an implementation it should return an error. Note that if we tried to run this command now then we would get an error. This is because we already removed all of the modules other than ``addr_gen``. We @@ -218,18 +224,17 @@ could restart our shell session, but instead let's use two new commands: :end-before: yosys> proc :caption: reloading :file:`fifo.v` and running :yoscrypt:`hierarchy -check -top fifo` -Notice how this time we didn't see any of those `$abstract` modules? That's +Notice how this time we didn't see any of those ``$abstract`` modules? That's because when we ran ``yosys fifo.v``, the first command Yosys called was :yoscrypt:`read_verilog -defer fifo.v`. The ``-defer`` option there tells -:cmd:ref:`read_verilog` only read the abstract syntax tree and defer actual -compilation to a later :cmd:ref:`hierarchy` command. This is useful in cases -where the default parameters of modules yield invalid code which is not -synthesizable. This is why Yosys defers compilation automatically and is one of -the reasons why hierarchy should always be the first command after loading the -design. If we know that our design won't run into this issue, we can skip the -``-defer``. +`read_verilog` only read the abstract syntax tree and defer actual compilation +to a later `hierarchy` command. This is useful in cases where the default +parameters of modules yield invalid code which is not synthesizable. This is why +Yosys defers compilation automatically and is one of the reasons why hierarchy +should always be the first command after loading the design. If we know that +our design won't run into this issue, we can skip the ``-defer``. -.. todo:: :cmd:ref:`hierarchy` failure modes +.. todo:: `hierarchy` failure modes .. note:: @@ -243,19 +248,19 @@ design. If we know that our design won't run into this issue, we can skip the interactive terminal. :kbd:`ctrl+c` (i.e. SIGINT) will also end the terminal session but will return an error code rather than exiting gracefully. -We can also run :cmd:ref:`proc` now to finish off the full :ref:`synth_begin`. -Because the design schematic is quite large, we will be showing just the data -path for the ``rdata`` output. If you would like to see the entire design for -yourself, you can do so with :doc:`/cmd/show`. Note that the :cmd:ref:`show` -command only works with a single module, so you may need to call it with -:yoscrypt:`show fifo`. :ref:`show_intro` section in -:doc:`/getting_started/scripting_intro` has more on how to use :cmd:ref:`show`. +We can also run `proc` now to finish off the full :ref:`synth_begin`. Because +the design schematic is quite large, we will be showing just the data path for +the ``rdata`` output. If you would like to see the entire design for yourself, +you can do so with :doc:`/cmd/show`. Note that the `show` command only works +with a single module, so you may need to call it with :yoscrypt:`show fifo`. +:ref:`show_intro` section in :doc:`/getting_started/scripting_intro` has more on +how to use `show`. .. figure:: /_images/code_examples/fifo/rdata_proc.* :class: width-helper invert-helper :name: rdata_proc - ``rdata`` output after :cmd:ref:`proc` + ``rdata`` output after `proc` The highlighted ``fifo_reader`` block contains an instance of the :ref:`addr_gen_proc` that we looked at earlier. Notice how the type is shown as @@ -263,10 +268,10 @@ The highlighted ``fifo_reader`` block contains an instance of the instance of the ``addr_gen`` module with the ``MAX_DATA`` parameter set to the given value. -The other highlighted block is a ``$memrd`` cell. At this stage of synthesis we +The other highlighted block is a `$memrd` cell. At this stage of synthesis we don't yet know what type of memory is going to be implemented, but we *do* know that ``rdata <= data[raddr];`` could be implemented as a read from memory. Note -that the ``$memrd`` cell here is asynchronous, with both the clock and enable +that the `$memrd` cell here is asynchronous, with both the clock and enable signal undefined; shown with the ``1'x`` inputs. .. seealso:: Advanced usage docs for @@ -276,7 +281,7 @@ Flattening ~~~~~~~~~~ At this stage of a synthesis flow there are a few other commands we could run. -In :cmd:ref:`synth_ice40` we get these: +In `synth_ice40` we get these: .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -286,7 +291,7 @@ In :cmd:ref:`synth_ice40` we get these: :name: synth_flatten :caption: ``flatten`` section -First off is :cmd:ref:`flatten`. Flattening the design like this can allow for +First off is `flatten`. Flattening the design like this can allow for optimizations between modules which would otherwise be missed. Let's run :yoscrypt:`flatten;;` on our design. @@ -309,23 +314,22 @@ optimizations between modules which would otherwise be missed. Let's run The pieces have moved around a bit, but we can see :ref:`addr_gen_proc` from earlier has replaced the ``fifo_reader`` block in :ref:`rdata_proc`. We can also see that the ``addr`` output has been renamed to :file:`fifo_reader.addr` -and merged with the ``raddr`` wire feeding into the ``$memrd`` cell. This wire -merging happened during the call to :cmd:ref:`clean` which we can see in the +and merged with the ``raddr`` wire feeding into the `$memrd` cell. This wire +merging happened during the call to `clean` which we can see in the :ref:`flat_clean`. .. note:: - :cmd:ref:`flatten` and :cmd:ref:`clean` would normally be combined into a + `flatten` and `clean` would normally be combined into a single :yoterm:`yosys> flatten;;` output, but they appear separately here as - a side effect of using :cmd:ref:`echo` for generating the terminal style + a side effect of using `echo` for generating the terminal style output. Depending on the target architecture, this stage of synthesis might also see -commands such as :cmd:ref:`tribuf` with the ``-logic`` option and -:cmd:ref:`deminout`. These remove tristate and inout constructs respectively, -replacing them with logic suitable for mapping to an FPGA. Since we do not have -any such constructs in our example running these commands does not change our -design. +commands such as `tribuf` with the ``-logic`` option and `deminout`. These +remove tristate and inout constructs respectively, replacing them with logic +suitable for mapping to an FPGA. Since we do not have any such constructs in +our example running these commands does not change our design. The coarse-grain representation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -342,9 +346,9 @@ optimizations and other transformations done previously. .. note:: - While the iCE40 flow had a :ref:`synth_flatten` and put :cmd:ref:`proc` in - the :ref:`synth_begin`, some synthesis scripts will instead include these in - this section. + While the iCE40 flow had a :ref:`synth_flatten` and put `proc` in the + :ref:`synth_begin`, some synthesis scripts will instead include these in this + section. Part 1 ^^^^^^ @@ -359,36 +363,35 @@ In the iCE40 flow, we start with the following commands: :caption: ``coarse`` section (part 1) :name: synth_coarse1 -We've already come across :cmd:ref:`opt_expr`, and :cmd:ref:`opt_clean` is the -same as :cmd:ref:`clean` but with more verbose output. The :cmd:ref:`check` -pass identifies a few obvious problems which will cause errors later. Calling -it here lets us fail faster rather than wasting time on something we know is -impossible. +We've already come across `opt_expr`, and `opt_clean` is the same as `clean` but +with more verbose output. The `check` pass identifies a few obvious problems +which will cause errors later. Calling it here lets us fail faster rather than +wasting time on something we know is impossible. Next up is :yoscrypt:`opt -nodffe -nosdff` performing a set of simple optimizations on the design. This command also ensures that only a specific subset of FF types are included, in preparation for the next command: -:doc:`/cmd/fsm`. Both :cmd:ref:`opt` and :cmd:ref:`fsm` are macro commands -which are explored in more detail in :doc:`/using_yosys/synthesis/opt` and +:doc:`/cmd/fsm`. Both `opt` and `fsm` are macro commands which are explored in +more detail in :doc:`/using_yosys/synthesis/opt` and :doc:`/using_yosys/synthesis/fsm` respectively. Up until now, the data path for ``rdata`` has remained the same since -:ref:`rdata_flat`. However the next call to :cmd:ref:`opt` does cause a change. -Specifically, the call to :cmd:ref:`opt_dff` without the ``-nodffe -nosdff`` -options is able to fold one of the ``$mux`` cells into the ``$adff`` to form an -``$adffe`` cell; highlighted below: +:ref:`rdata_flat`. However the next call to `opt` does cause a change. +Specifically, the call to `opt_dff` without the ``-nodffe -nosdff`` options is +able to fold one of the `$mux` cells into the `$adff` to form an `$adffe` cell; +highlighted below: .. literalinclude:: /code_examples/fifo/fifo.out :language: doscon :start-at: yosys> opt_dff :end-before: yosys> select - :caption: output of :cmd:ref:`opt_dff` + :caption: output of `opt_dff` .. figure:: /_images/code_examples/fifo/rdata_adffe.* :class: width-helper invert-helper :name: rdata_adffe - ``rdata`` output after :cmd:ref:`opt_dff` + ``rdata`` output after `opt_dff` .. seealso:: Advanced usage docs for @@ -414,27 +417,27 @@ First up is :doc:`/cmd/wreduce`. If we run this we get the following: :language: doscon :start-at: yosys> wreduce :end-before: yosys> select - :caption: output of :cmd:ref:`wreduce` + :caption: output of `wreduce` Looking at the data path for ``rdata``, the most relevant of these width reductions are the ones affecting ``fifo.$flatten\fifo_reader.$add$fifo.v``. -That is the ``$add`` cell incrementing the fifo_reader address. We can look at +That is the `$add` cell incrementing the fifo_reader address. We can look at the schematic and see the output of that cell has now changed. -.. todo:: pending bugfix in :cmd:ref:`wreduce` and/or :cmd:ref:`opt_clean` +.. todo:: pending bugfix in `wreduce` and/or `opt_clean` .. figure:: /_images/code_examples/fifo/rdata_wreduce.* :class: width-helper invert-helper :name: rdata_wreduce - ``rdata`` output after :cmd:ref:`wreduce` + ``rdata`` output after `wreduce` The next two (new) commands are :doc:`/cmd/peepopt` and :doc:`/cmd/share`. Neither of these affect our design, and they're explored in more detail in :doc:`/using_yosys/synthesis/opt`, so let's skip over them. :yoscrypt:`techmap -map +/cmp2lut.v -D LUT_WIDTH=4` optimizes certain comparison operators by -converting them to LUTs instead. The usage of :cmd:ref:`techmap` is explored -more in :doc:`/using_yosys/synthesis/techmap_synth`. +converting them to LUTs instead. The usage of `techmap` is explored more in +:doc:`/using_yosys/synthesis/techmap_synth`. Our next command to run is :doc:`/cmd/memory_dff`. @@ -443,17 +446,17 @@ Our next command to run is :language: doscon :start-at: yosys> memory_dff :end-before: yosys> select - :caption: output of :cmd:ref:`memory_dff` + :caption: output of `memory_dff` .. figure:: /_images/code_examples/fifo/rdata_memrdv2.* :class: width-helper invert-helper :name: rdata_memrdv2 - ``rdata`` output after :cmd:ref:`memory_dff` + ``rdata`` output after `memory_dff` -As the title suggests, :cmd:ref:`memory_dff` has merged the output ``$dff`` into -the ``$memrd`` cell and converted it to a ``$memrd_v2`` (highlighted). This has -also connected the ``CLK`` port to the ``clk`` input as it is now a synchronous +As the title suggests, `memory_dff` has merged the output `$dff` into the +`$memrd` cell and converted it to a `$memrd_v2` (highlighted). This has also +connected the ``CLK`` port to the ``clk`` input as it is now a synchronous memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and ``SRST=1'0``) inputs. @@ -466,12 +469,11 @@ memory read with appropriate enable (``EN=1'1``) and reset (``ARST=1'0`` and Part 3 ^^^^^^ -The third part of the :cmd:ref:`synth_ice40` flow is a series of commands for -mapping to DSPs. By default, the iCE40 flow will not map to the hardware DSP -blocks and will only be performed if called with the ``-dsp`` flag: -:yoscrypt:`synth_ice40 -dsp`. While our example has nothing that could be -mapped to DSPs we can still take a quick look at the commands here and describe -what they do. +The third part of the `synth_ice40` flow is a series of commands for mapping to +DSPs. By default, the iCE40 flow will not map to the hardware DSP blocks and +will only be performed if called with the ``-dsp`` flag: :yoscrypt:`synth_ice40 +-dsp`. While our example has nothing that could be mapped to DSPs we can still +take a quick look at the commands here and describe what they do. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -482,29 +484,27 @@ what they do. :name: synth_coarse3 :yoscrypt:`wreduce t:$mul` performs width reduction again, this time targetting -only cells of type ``$mul``. :yoscrypt:`techmap -map +/mul2dsp.v -map -+/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses :cmd:ref:`techmap` to map -``$mul`` cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40 -``SB_MAC16``. Any multipliers which aren't compatible with conversion to -``$__MUL16X16`` are relabelled to ``$__soft_mul`` before :cmd:ref:`chtype` -changes them back to ``$mul``. +only cells of type `$mul`. :yoscrypt:`techmap -map +/mul2dsp.v -map ++/ice40/dsp_map.v ... -D DSP_NAME=$__MUL16X16` uses `techmap` to map `$mul` +cells to ``$__MUL16X16`` which are, in turn, mapped to the iCE40 ``SB_MAC16``. +Any multipliers which aren't compatible with conversion to ``$__MUL16X16`` are +relabelled to ``$__soft_mul`` before `chtype` changes them back to `$mul`. During the mul2dsp conversion, some of the intermediate signals are marked with the attribute ``mul2dsp``. By calling :yoscrypt:`select a:mul2dsp` we restrict the following commands to only operate on the cells and wires used for these -signals. :cmd:ref:`setattr` removes the now unnecessary ``mul2dsp`` attribute. -:cmd:ref:`opt_expr` we've already come across for const folding and simple -expression rewriting, the ``-fine`` option just enables more fine-grain -optimizations. Then we perform width reduction a final time and clear the -selection. +signals. `setattr` removes the now unnecessary ``mul2dsp`` attribute. +`opt_expr` we've already come across for const folding and simple expression +rewriting, the ``-fine`` option just enables more fine-grain optimizations. +Then we perform width reduction a final time and clear the selection. .. todo:: ``ice40_dsp`` is pmgen -Finally we have :cmd:ref:`ice40_dsp`: similar to the :cmd:ref:`memory_dff` -command we saw in the previous section, this merges any surrounding registers -into the ``SB_MAC16`` cell. This includes not just the input/output registers, -but also pipeline registers and even a post-adder where applicable: turning a -multiply + add into a single multiply-accumulate. +Finally we have `ice40_dsp`: similar to the `memory_dff` command we saw in the +previous section, this merges any surrounding registers into the ``SB_MAC16`` +cell. This includes not just the input/output registers, but also pipeline +registers and even a post-adder where applicable: turning a multiply + add into +a single multiply-accumulate. .. seealso:: Advanced usage docs for :doc:`/using_yosys/synthesis/techmap_synth` @@ -522,44 +522,43 @@ That brings us to the fourth and final part for the iCE40 synthesis flow: :caption: ``coarse`` section (part 4) :name: synth_coarse4 -Where before each type of arithmetic operation had its own cell, e.g. ``$add``, -we now want to extract these into ``$alu`` and ``$macc`` cells which can help -identify opportunities for reusing logic. We do this by running -:cmd:ref:`alumacc`, which we can see produce the following changes in our -example design: +Where before each type of arithmetic operation had its own cell, e.g. `$add`, we +now want to extract these into `$alu` and `$macc_v2` cells which can help identify +opportunities for reusing logic. We do this by running `alumacc`, which we can +see produce the following changes in our example design: .. literalinclude:: /code_examples/fifo/fifo.out :language: doscon :start-at: yosys> alumacc :end-before: yosys> select - :caption: output of :cmd:ref:`alumacc` + :caption: output of `alumacc` .. figure:: /_images/code_examples/fifo/rdata_alumacc.* :class: width-helper invert-helper :name: rdata_alumacc - ``rdata`` output after :cmd:ref:`alumacc` + ``rdata`` output after `alumacc` -Once these cells have been inserted, the call to :cmd:ref:`opt` can combine -cells which are now identical but may have been missed due to e.g. the -difference between ``$add`` and ``$sub``. +Once these cells have been inserted, the call to `opt` can combine cells which +are now identical but may have been missed due to e.g. the difference between +`$add` and `$sub`. -The other new command in this part is :doc:`/cmd/memory`. :cmd:ref:`memory` is -another macro command which we examine in more detail in +The other new command in this part is :doc:`/cmd/memory`. `memory` is another +macro command which we examine in more detail in :doc:`/using_yosys/synthesis/memory`. For this document, let us focus just on -the step most relevant to our example: :cmd:ref:`memory_collect`. Up until this -point, our memory reads and our memory writes have been totally disjoint cells; -operating on the same memory only in the abstract. :cmd:ref:`memory_collect` -combines all of the reads and writes for a memory block into a single cell. +the step most relevant to our example: `memory_collect`. Up until this point, +our memory reads and our memory writes have been totally disjoint cells; +operating on the same memory only in the abstract. `memory_collect` combines all +of the reads and writes for a memory block into a single cell. .. figure:: /_images/code_examples/fifo/rdata_coarse.* :class: width-helper invert-helper :name: rdata_coarse - ``rdata`` output after :cmd:ref:`memory_collect` + ``rdata`` output after `memory_collect` -Looking at the schematic after running :cmd:ref:`memory_collect` we see that our -``$memrd_v2`` cell has been replaced with a ``$mem_v2`` cell named ``data``, the +Looking at the schematic after running `memory_collect` we see that our +`$memrd_v2` cell has been replaced with a `$mem_v2` cell named ``data``, the same name that we used in :ref:`fifo-v`. Where before we had a single set of signals for address and enable, we now have one set for reading (``RD_*``) and one for writing (``WR_*``), as well as both ``WR_DATA`` input and ``RD_DATA`` @@ -592,8 +591,8 @@ If you skipped calling :yoscrypt:`read_verilog -D ICE40_HX -lib -specify Memory blocks ^^^^^^^^^^^^^ -Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap` and -:cmd:ref:`techmap`. +Mapping to hard memory blocks uses a combination of `memory_libmap` and +`techmap`. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -609,28 +608,28 @@ Mapping to hard memory blocks uses a combination of :cmd:ref:`memory_libmap` and ``rdata`` output after :ref:`map_ram` -The :ref:`map_ram` converts the generic ``$mem_v2`` into the iCE40 -``SB_RAM40_4K`` (highlighted). We can also see the memory address has been -remapped, and the data bits have been reordered (or swizzled). There is also -now a ``$mux`` cell controlling the value of ``rdata``. In :ref:`fifo-v` we -wrote our memory as read-before-write, however the ``SB_RAM40_4K`` has undefined -behaviour when reading from and writing to the same address in the same cycle. -As a result, extra logic is added so that the generated circuit matches the -behaviour of the verilog. :ref:`no_rw_check` describes how we could change our -verilog to match our hardware instead. +The :ref:`map_ram` converts the generic `$mem_v2` into the iCE40 ``SB_RAM40_4K`` +(highlighted). We can also see the memory address has been remapped, and the +data bits have been reordered (or swizzled). There is also now a `$mux` cell +controlling the value of ``rdata``. In :ref:`fifo-v` we wrote our memory as +read-before-write, however the ``SB_RAM40_4K`` has undefined behaviour when +reading from and writing to the same address in the same cycle. As a result, +extra logic is added so that the generated circuit matches the behaviour of the +verilog. :ref:`no_rw_check` describes how we could change our verilog to match +our hardware instead. -If we run :cmd:ref:`memory_libmap` under the :cmd:ref:`debug` command we can see -candidates which were identified for mapping, along with the costs of each and -what logic requires emulation. +If we run `memory_libmap` under the `debug` command we can see candidates which +were identified for mapping, along with the costs of each and what logic +requires emulation. .. literalinclude:: /code_examples/fifo/fifo.libmap :language: doscon :lines: 2, 6- The ``$__ICE40_RAM4K_`` cell is defined in the file |techlibs/ice40/brams.txt|_, -with the mapping to ``SB_RAM40_4K`` done by :cmd:ref:`techmap` using +with the mapping to ``SB_RAM40_4K`` done by `techmap` using |techlibs/ice40/brams_map.v|_. Any leftover memory cells are then converted -into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`. +into flip flops (the ``logic fallback``) with `memory_map`. .. |techlibs/ice40/brams.txt| replace:: :file:`techlibs/ice40/brams.txt` .. _techlibs/ice40/brams.txt: https://github.com/YosysHQ/yosys/tree/main/techlibs/ice40/brams.txt @@ -654,8 +653,8 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`. .. note:: The visual clutter on the ``RDATA`` output port (highlighted) is an - unfortunate side effect of :cmd:ref:`opt_clean` on the swizzled data bits. In - connecting the ``$mux`` input port directly to ``RDATA`` to reduce the number + unfortunate side effect of `opt_clean` on the swizzled data bits. In + connecting the `$mux` input port directly to ``RDATA`` to reduce the number of wires, the ``$techmap579\data.0.0.RDATA`` wire becomes more visually complex. @@ -667,11 +666,10 @@ into flip flops (the ``logic fallback``) with :cmd:ref:`memory_map`. Arithmetic ^^^^^^^^^^ -Uses :cmd:ref:`techmap` to map basic arithmetic logic to hardware. This sees -somewhat of an explosion in cells as multi-bit ``$mux`` and ``$adffe`` are -replaced with single-bit ``$_MUX_`` and ``$_DFFE_PP0P_`` cells, while the -``$alu`` is replaced with primitive ``$_OR_`` and ``$_NOT_`` gates and a -``$lut`` cell. +Uses `techmap` to map basic arithmetic logic to hardware. This sees somewhat of +an explosion in cells as multi-bit `$mux` and `$adffe` are replaced with +single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the `$alu` is replaced with +primitive `$_OR_` and `$_NOT_` gates and a `$lut` cell. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -693,14 +691,14 @@ replaced with single-bit ``$_MUX_`` and ``$_DFFE_PP0P_`` cells, while the Flip-flops ^^^^^^^^^^ -Convert FFs to the types supported in hardware with :cmd:ref:`dfflegalize`, and -then use :cmd:ref:`techmap` to map them. In our example, this converts the -``$_DFFE_PP0P_`` cells to ``SB_DFFER``. +Convert FFs to the types supported in hardware with `dfflegalize`, and then use +`techmap` to map them. In our example, this converts the `$_DFFE_PP0P_` cells +to ``SB_DFFER``. -We also run :cmd:ref:`simplemap` here to convert any remaining cells which could -not be mapped to hardware into gate-level primitives. This includes optimizing -``$_MUX_`` cells where one of the inputs is a constant ``1'0``, replacing it -instead with an ``$_AND_`` cell. +We also run `simplemap` here to convert any remaining cells which could not be +mapped to hardware into gate-level primitives. This includes optimizing +`$_MUX_` cells where one of the inputs is a constant ``1'0``, replacing it +instead with an `$_AND_` cell. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -722,11 +720,10 @@ instead with an ``$_AND_`` cell. LUTs ^^^^ -:cmd:ref:`abc` and :cmd:ref:`techmap` are used to map LUTs; converting primitive -cell types to use ``$lut`` and ``SB_CARRY`` cells. Note that the iCE40 flow -uses :cmd:ref:`abc9` rather than :cmd:ref:`abc`. For more on what these do, and -what the difference between these two commands are, refer to -:doc:`/using_yosys/synthesis/abc`. +`abc` and `techmap` are used to map LUTs; converting primitive cell types to use +`$lut` and ``SB_CARRY`` cells. Note that the iCE40 flow uses `abc9` rather than +`abc`. For more on what these do, and what the difference between these two +commands are, refer to :doc:`/using_yosys/synthesis/abc`. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -742,8 +739,8 @@ what the difference between these two commands are, refer to ``rdata`` output after :ref:`map_luts` -Finally we use :cmd:ref:`techmap` to map the generic ``$lut`` cells to iCE40 -``SB_LUT4`` cells. +Finally we use `techmap` to map the generic `$lut` cells to iCE40 ``SB_LUT4`` +cells. .. literalinclude:: /cmd/synth_ice40.rst :language: yoscrypt @@ -769,12 +766,12 @@ Other cells The following commands may also be used for mapping other cells: -:cmd:ref:`hilomap` +`hilomap` Some architectures require special driver cells for driving a constant hi or lo value. This command replaces simple constants with instances of such driver cells. -:cmd:ref:`iopadmap` +`iopadmap` Top-level input/outputs must usually be implemented using special I/O-pad cells. This command inserts such cells to the design. @@ -801,28 +798,27 @@ The new commands here are: - :doc:`/cmd/stat`, and - :doc:`/cmd/blackbox`. -The output from :cmd:ref:`stat` is useful for checking resource utilization; -providing a list of cells used in the design and the number of each, as well as -the number of other resources used such as wires and processes. For this -design, the final call to :cmd:ref:`stat` should look something like the -following: +The output from `stat` is useful for checking resource utilization; providing a +list of cells used in the design and the number of each, as well as the number +of other resources used such as wires and processes. For this design, the final +call to `stat` should look something like the following: .. literalinclude:: /code_examples/fifo/fifo.stat :language: doscon :start-at: yosys> stat -top fifo -Note that the :yoscrypt:`-top fifo` here is optional. :cmd:ref:`stat` will -automatically use the module with the ``top`` attribute set, which ``fifo`` was -when we called :cmd:ref:`hierarchy`. If no module is marked ``top``, then stats -will be shown for each module selected. +Note that the :yoscrypt:`-top fifo` here is optional. `stat` will automatically +use the module with the ``top`` attribute set, which ``fifo`` was when we called +`hierarchy`. If no module is marked ``top``, then stats will be shown for each +module selected. -The :cmd:ref:`stat` output is also useful as a kind of sanity-check: Since we -have already run :cmd:ref:`proc`, we wouldn't expect there to be any processes. -We also expect ``data`` to use hard memory; if instead of an ``SB_RAM40_4K`` saw -a high number of flip-flops being used we might suspect something was wrong. +The `stat` output is also useful as a kind of sanity-check: Since we have +already run `proc`, we wouldn't expect there to be any processes. We also expect +``data`` to use hard memory; if instead of an ``SB_RAM40_4K`` saw a high number +of flip-flops being used we might suspect something was wrong. -If we instead called :cmd:ref:`stat` immediately after :yoscrypt:`read_verilog -fifo.v` we would see something very different: +If we instead called `stat` immediately after :yoscrypt:`read_verilog fifo.v` we +would see something very different: .. literalinclude:: /code_examples/fifo/fifo.stat :language: doscon @@ -845,10 +841,10 @@ The iCE40 synthesis flow has the following output modes available: As an example, if we called :yoscrypt:`synth_ice40 -top fifo -json fifo.json`, our synthesized ``fifo`` design will be output as :file:`fifo.json`. We can -then read the design back into Yosys with :cmd:ref:`read_json`, but make sure -you use :yoscrypt:`design -reset` or open a new interactive terminal first. The -JSON output we get can also be loaded into `nextpnr`_ to do place and route; but -that is beyond the scope of this documentation. +then read the design back into Yosys with `read_json`, but make sure you use +:yoscrypt:`design -reset` or open a new interactive terminal first. The JSON +output we get can also be loaded into `nextpnr`_ to do place and route; but that +is beyond the scope of this documentation. .. _nextpnr: https://github.com/YosysHQ/nextpnr diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index 4d1a2f36a..fe96b2314 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -34,37 +34,40 @@ Targeted architectures The `OSS CAD Suite`_ releases `nightly builds`_ for the following architectures: -.. only:: html +- **linux-x64** - Most personal Linux based computers +- **darwin-x64** - macOS 12 or later with Intel CPU +- **darwin-arm64** - macOS 12 or later with M1/M2 CPU +- **windows-x64** - Targeted for Windows 10 and 11 +- **linux-arm64** - Devices such as Raspberry Pi with 64bit OS - - linux-x64 |linux-x64| - - Most personal Linux based computers - - - darwin-x64 |darwin-x64| - - macOS 12 or later with Intel CPU - - - darwin-arm64 |darwin-arm64| - - macOS 12 or later with M1/M2 CPU - - - windows-x64 |windows-x64| - - Targeted for Windows 10 and 11 - - - linux-arm64 |linux-arm64| +For more information about the targeted architectures, and the current build +status, check the `OSS CAD Suite`_ git repository. .. _OSS CAD Suite: https://github.com/YosysHQ/oss-cad-suite-build .. _nightly builds: https://github.com/YosysHQ/oss-cad-suite-build/releases/latest -.. |linux-x64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-x64.yml/badge.svg -.. |darwin-x64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/darwin-x64.yml/badge.svg -.. |darwin-arm64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/darwin-arm64.yml/badge.svg -.. |windows-x64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/windows-x64.yml/badge.svg -.. |linux-arm64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-arm64.yml/badge.svg - Building from source ~~~~~~~~~~~~~~~~~~~~ -Refer to the `readme`_ for the most up-to-date install instructions. +The Yosys source files can be obtained from the `YosysHQ/Yosys git repository`_. +`ABC`_ and some of the other libraries used are included as git submodules. To +clone these submodules at the same time, use e.g.: -.. _readme: https://github.com/YosysHQ/yosys#building-from-source +.. code:: console + + git clone --recurse-submodules https://github.com/YosysHQ/yosys.git # ..or.. + git clone https://github.com/YosysHQ/yosys.git + cd yosys + git submodule update --init --recursive + +.. _YosysHQ/Yosys git repository: https://github.com/yosyshq/yosys/ +.. _ABC: https://github.com/berkeley-abc/abc + +.. note:: + + As of Yosys v0.47, releases include a ``yosys.tar.gz`` file which includes + all source code and all sub-modules in a single archive. This can be used as + an alternative which does not rely on ``git``. Supported platforms ^^^^^^^^^^^^^^^^^^^ @@ -88,53 +91,141 @@ A C++ compiler with C++17 support is required as well as some standard tools such as GNU Flex, GNU Bison, Make and Python. Some additional tools: readline, libffi, Tcl and zlib; are optional but enabled by default (see :makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the -:cmd:ref:`show` command to display schematics. +`show` command to display schematics. Installing all prerequisites for Ubuntu 20.04: .. code:: console - sudo sudo apt-get install build-essential clang lld bison flex \ - libreadline-dev gawk tcl-dev libffi-dev git make \ - graphviz xdot pkg-config python3 libboost-system-dev \ + sudo apt-get install gperf build-essential bison flex \ + libreadline-dev gawk tcl-dev libffi-dev git graphviz \ + xdot pkg-config python3 libboost-system-dev \ libboost-python-dev libboost-filesystem-dev zlib1g-dev -Installing all prerequisites for macOS 11 (with Homebrew): +Installing all prerequisites for macOS 13 (with Homebrew): .. code:: console - brew install bison flex gawk libffi git graphviz \ - pkg-config python3 tcl-tk xdot bash boost-python3 + brew tap Homebrew/bundle && brew bundle + +or MacPorts: + +.. code:: console + + sudo port install bison flex readline gawk libffi graphviz \ + pkgconfig python311 boost zlib tcl + +On FreeBSD use the following command to install all prerequisites: + +.. code:: console + + pkg install bison flex readline gawk libffi graphviz \ + pkgconf python311 tcl-wrapper boost-libs + +.. note:: On FreeBSD system use gmake instead of make. To run tests use: + ``MAKE=gmake CXX=cxx CC=cc gmake test`` + +For Cygwin use the following command to install all prerequisites, or select these additional packages: + +.. code:: console + + setup-x86_64.exe -q --packages=bison,flex,gcc-core,gcc-g++,git,libffi-devel,libreadline-devel,make,pkg-config,python3,tcl-devel,boost-build,zlib-devel + +.. warning:: + + As of this writing, Cygwin only supports up to Python 3.9.16 while the + minimum required version of Python is 3.11. This means that Cygwin is not + compatible with many of the Python-based frontends. While this does not + currently prevent Yosys itself from working, no guarantees are made for + continued support. It is instead recommended to use Windows Subsystem for + Linux (WSL) and follow the instructions for Ubuntu. + +.. + For MSYS2 (MINGW64): + + .. code:: console + + pacman -S bison flex mingw-w64-x86_64-gcc git libffi-devel libreadline-devel make pkg-config python3 tcl-devel mingw-w64-x86_64-boost zlib-devel + + Not that I can get this to work; it's failing during ld with what looks like + math library issues: ``multiple definition of `tanh'`` and + ``undefined reference to `__imp_acosh'``, as well as issues in `aiger2` with + ``seekg`` et al not being available. + + .. note:: + + The ``config-msys2-64`` target uses the ``mingw-w64-x86_64-`` prefixed + compiler in order to allow compiled exe files to be run without an MSYS2 + shell. + +Build configuration +^^^^^^^^^^^^^^^^^^^ + +The Yosys build is based solely on Makefiles, and uses a number of variables +which influence the build process. The recommended method for configuring +builds is with a ``Makefile.conf`` file in the root ``yosys`` directory. The +following commands will clean the directory and provide an initial configuration +file: + +.. code:: console + + make config-clang # ..or.. + make config-gcc + +Check the root Makefile to see what other configuration targets are available. +Other variables can then be added to the ``Makefile.conf`` as needed, for +example: + +.. code:: console + + echo "ENABLE_ZLIB := 0" >> Makefile.conf + +Using one of these targets will set the ``CONFIG`` variable to something other +than ``none``, and will override the environment variable for ``CXX``. To use a +different compiler than the default when building, use: + +.. code:: console + + make CXX=$CXX # ..or.. + make CXX="g++-11" + +.. note:: + + Setting the compiler in this way will prevent some other options such as + ``ENABLE_CCACHE`` from working as expected. + +If you have clang, and (a compatible version of) ``ld.lld`` available in PATH, +it's recommended to speed up incremental builds with lld by enabling LTO with +``ENABLE_LTO=1``. On macOS, LTO requires using clang from homebrew rather than +clang from xcode. For example: + +.. code:: console + + make ENABLE_LTO=1 CXX=$(brew --prefix)/opt/llvm/bin/clang++ + +By default, building (and installing) yosys will build (and install) `ABC`_, +using :program:`yosys-abc` as the executable name. To use an existing ABC +executable instead, set the ``ABCEXTERNAL`` make variable to point to the +desired executable. Running the build system ^^^^^^^^^^^^^^^^^^^^^^^^ -From the root `yosys` directory, call the following commands: +From the root ``yosys`` directory, call the following commands: .. code:: console make sudo make install -This will build and then install Yosys, making it available on the command line -as `yosys`. Note that this also downloads, builds, and installs `ABC`_ (using -:program:`yosys-abc` as the executable name). - -.. _ABC: https://github.com/berkeley-abc/abc - -The default compiler is ``clang``, to change between ``clang`` and ``gcc``, use -one of the following: +To use a separate (out-of-tree) build directory, provide a path to the Makefile. .. code:: console - make config-clang - make config-gcc + mkdir build; cd build + make -f ../Makefile -To use a compiler different than the default, use: - -.. code:: console - - make CXX="g++-11" +Out-of-tree builds require a clean source tree. .. seealso:: @@ -161,10 +252,6 @@ directories: ``frontends/`` This directory contains a subdirectory for each of the frontend modules. -``guidelines/`` - Contains developer guidelines, including the code of conduct and coding style - guide. - ``kernel/`` This directory contains all the core functionality of Yosys. This includes the functions and definitions for working with the RTLIL data structures @@ -184,9 +271,8 @@ directories: ``passes/`` This directory contains a subdirectory for each pass or group of passes. For - example as of this writing the directory :file:`passes/hierarchy/` contains the - code for three passes: :cmd:ref:`hierarchy`, :cmd:ref:`submod`, and - :cmd:ref:`uniquify`. + example as of this writing the directory :file:`passes/hierarchy/` contains + the code for three passes: `hierarchy`, `submod`, and `uniquify`. ``techlibs/`` This directory contains simulation models and standard implementations for @@ -207,9 +293,6 @@ commands. Good starting points for reading example source code to learn how to write passes are :file:`passes/opt/opt_dff.cc` and :file:`passes/opt/opt_merge.cc`. -See the top-level README file for a quick Getting Started guide and build -instructions. The Yosys build is based solely on Makefiles. - Users of the Qt Creator IDE can generate a QT Creator project file using make qtcreator. Users of the Eclipse IDE can use the "Makefile Project with Existing Code" project type in the Eclipse "New Project" dialog (only available after the diff --git a/docs/source/getting_started/scripting_intro.rst b/docs/source/getting_started/scripting_intro.rst index a6b4cb6bb..01954c661 100644 --- a/docs/source/getting_started/scripting_intro.rst +++ b/docs/source/getting_started/scripting_intro.rst @@ -7,8 +7,7 @@ file format and how you can make your own synthesis scripts. Yosys script files typically use the :file:`.ys` extension and contain a set of commands for Yosys to run sequentially. These commands are the same ones we -were using on the previous page like :cmd:ref:`read_verilog` and -:cmd:ref:`hierarchy`. +were using on the previous page like `read_verilog` and `hierarchy`. Script parsing ~~~~~~~~~~~~~~ @@ -39,9 +38,9 @@ Another special character that can be used in Yosys scripts is the bang ``!``. Anything after the bang will be executed as a shell command. This can only be terminated with a new line. Any semicolons, hashes, or other special characters will be passed to the shell. If an error code is returned from the shell it -will be raised by Yosys. :cmd:ref:`exec` provides a much more flexible way of -executing commands, allowing the output to be logged and more control over when -to generate errors. +will be raised by Yosys. `exec` provides a much more flexible way of executing +commands, allowing the output to be logged and more control over when to +generate errors. The synthesis starter script ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -62,24 +61,23 @@ already, let's take a look at some of those script files now. :caption: A section of :file:`fifo.ys`, generating the images used for :ref:`addr_gen_example` :name: fifo-ys -The first command there, :yoscrypt:`echo on`, uses :cmd:ref:`echo` to enable -command echoes on. This is how we generated the code listing for +The first command there, :yoscrypt:`echo on`, uses `echo` to enable command +echoes on. This is how we generated the code listing for :ref:`hierarchy_output`. Turning command echoes on prints the ``yosys> hierarchy -top addr_gen`` line, making the output look the same as if it were an interactive terminal. :yoscrypt:`hierarchy -top addr_gen` is of course the command we were demonstrating, including the output text and an image of the design schematic after running it. -We briefly touched on :cmd:ref:`select` when it came up in -:cmd:ref:`synth_ice40`, but let's look at it more now. +We briefly touched on `select` when it came up in `synth_ice40`, but let's look +at it more now. .. _select_intro: Selections intro ^^^^^^^^^^^^^^^^ -The :cmd:ref:`select` command is used to modify and view the list of selected -objects: +The `select` command is used to modify and view the list of selected objects: .. literalinclude:: /code_examples/fifo/fifo.out :language: doscon @@ -99,7 +97,7 @@ signifies we are matching on the *cell type*, and the ``*`` means to match anything. For this (very simple) selection, we are trying to find all of the cells, regardless of their type. The active selection is now shown as ``[addr_gen]*``, indicating some sub-selection of the ``addr_gen`` module. This -gives us the ``$add`` and ``$eq`` cells, which we want to highlight for the +gives us the `$add` and `$eq` cells, which we want to highlight for the :ref:`addr_gen_hier` image. .. _select_new_cells: @@ -111,15 +109,16 @@ by referring to it as ``@new_cells``, which we will see later. Then we clear the selection so that the following commands can operate on the full design. While we split that out for this document, we could have done the same thing in a single line by calling :yoscrypt:`select -set new_cells addr_gen/t:*`. If we -know we only have the one module in our design, we can even skip the `addr_gen/` -part. Looking further down :ref:`the fifo.ys code ` we can see this -with :yoscrypt:`select -set new_cells t:$mux t:*dff`. We can also see in that -command that selections don't have to be limited to a single statement. +know we only have the one module in our design, we can even skip the +``addr_gen/`` part. Looking further down :ref:`the fifo.ys code ` we +can see this with :yoscrypt:`select -set new_cells t:$mux t:*dff`. We can also +see in that command that selections don't have to be limited to a single +statement. Many commands also support an optional ``[selection]`` argument which can be used to override the currently selected objects. We could, for example, call -:yoscrypt:`clean addr_gen` to have :cmd:ref:`clean` operate on *just* the -``addr_gen`` module. +:yoscrypt:`clean addr_gen` to have `clean` operate on *just* the ``addr_gen`` +module. Detailed documentation of the select framework can be found under :doc:`/using_yosys/more_scripting/selections` or in the command reference at @@ -130,23 +129,23 @@ Detailed documentation of the select framework can be found under Displaying schematics ^^^^^^^^^^^^^^^^^^^^^ -While the :cmd:ref:`select` command is very useful, sometimes nothing beats -being able to see a design for yourself. This is where :cmd:ref:`show` comes -in. Note that this document is just an introduction to the :cmd:ref:`show` -command, only covering the basics. For more information, including a guide on -what the different symbols represent, see :ref:`interactive_show` and the +While the `select` command is very useful, sometimes nothing beats being able to +see a design for yourself. This is where `show` comes in. Note that this +document is just an introduction to the `show` command, only covering the +basics. For more information, including a guide on what the different symbols +represent, see :ref:`interactive_show` and the :doc:`/using_yosys/more_scripting/interactive_investigation` page. .. figure:: /_images/code_examples/fifo/addr_gen_show.* :class: width-helper invert-helper :name: addr_gen_show - Calling :yoscrypt:`show addr_gen` after :cmd:ref:`hierarchy` + Calling :yoscrypt:`show addr_gen` after `hierarchy` .. note:: - The :cmd:ref:`show` command requires a working installation of `GraphViz`_ - and `xdot`_ for displaying the actual circuit diagrams. + The `show` command requires a working installation of `GraphViz`_ and `xdot`_ + for displaying the actual circuit diagrams. .. _GraphViz: http://www.graphviz.org/ .. _xdot: https://github.com/jrfonseca/xdot.py @@ -160,8 +159,8 @@ we see the following: :start-at: -prefix addr_gen_show :end-before: yosys> show -Calling :cmd:ref:`show` with :yoscrypt:`-format dot` tells it we want to output -a :file:`.dot` file rather than opening it for display. The :yoscrypt:`-prefix +Calling `show` with :yoscrypt:`-format dot` tells it we want to output a +:file:`.dot` file rather than opening it for display. The :yoscrypt:`-prefix addr_gen_show` option indicates we want the file to be called :file:`addr_gen_show.{*}`. Remember, we do this in :file:`fifo.ys` because we need to store the image for displaying in the documentation you're reading. But @@ -184,8 +183,8 @@ like when we called :yoscrypt:`select -module addr_gen` in :ref:`select_intro`. That last parameter doesn't have to be a module name, it can be any valid selection string. Remember when we :ref:`assigned a name to a selection` and called it ``new_cells``? We saw in the -:yoscrypt:`select -list` output that it contained two cells, an ``$add`` and an -``$eq``. We can call :cmd:ref:`show` on that selection just as easily: +:yoscrypt:`select -list` output that it contained two cells, an `$add` and an +`$eq`. We can call `show` on that selection just as easily: .. figure:: /_images/code_examples/fifo/new_cells_show.* :class: width-helper invert-helper @@ -207,21 +206,20 @@ the two ``PROC`` blocks. To achieve this highlight, we make use of the Calling :yoscrypt:`show -color maroon3 @new_cells -color cornflowerblue p:* -notitle` -As described in the the :cmd:ref:`help` output for :cmd:ref:`show` (or by -clicking on the :cmd:ref:`show` link), colors are specified as :yoscrypt:`-color - `. Color names for the ```` portion can be found on the -`GraphViz color docs`_. Unlike the final :cmd:ref:`show` parameter which can -have be any selection string, the ```` part must be a single selection -expression or named selection. That means while we can use ``@new_cells``, we -couldn't use ``t:$eq t:$add``. In general, if a command lists ``[selection]`` -as its final parameter it can be any selection string. Any selections that are -not the final parameter, such as those used in options, must be a single -expression instead. +As described in the the `help` output for `show` (or by clicking on the `show` +link), colors are specified as :yoscrypt:`-color `. Color names +for the ```` portion can be found on the `GraphViz color docs`_. Unlike +the final `show` parameter which can have be any selection string, the +```` part must be a single selection expression or named selection. +That means while we can use ``@new_cells``, we couldn't use ``t:$eq t:$add``. +In general, if a command lists ``[selection]`` as its final parameter it can be +any selection string. Any selections that are not the final parameter, such as +those used in options, must be a single expression instead. .. _GraphViz color docs: https://graphviz.org/doc/info/colors -For all of the options available to :cmd:ref:`show`, check the command reference -at :doc:`/cmd/show`. +For all of the options available to `show`, check the command reference at +:doc:`/cmd/show`. .. seealso:: :ref:`interactive_show` on the :doc:`/using_yosys/more_scripting/interactive_investigation` page. diff --git a/docs/source/index.rst b/docs/source/index.rst index 106ddbab8..61dc114ef 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,38 +7,37 @@ see :doc:`/introduction`. For a quick guide on how to get started using Yosys, check out :doc:`/getting_started/index`. For the complete list of commands available, go to :ref:`commandindex`. -.. note:: - - This documentation recently went through a major restructure. If you're - looking for something from the previous version and can't find it here, - please `let us know`_. Documentation from before the restructure can still - be found by switching to `version 0.36`_ or earlier. Note that the previous - theme does not include a version switcher. - -.. _let us know: https://github.com/YosysHQ/yosys/issues/new/choose -.. _version 0.36: https://yosyshq.readthedocs.io/projects/yosys/en/0.36/ - .. todo:: look into command ref improvements - Search bar with live drop down suggestions for matching on title / autocompleting commands - Scroll the left sidebar to the current location on page load - - Also the formatting/linking in pdf is broken + - Also the formatting in pdf uses link formatting instead of code formatting .. todolist:: -.. only:: html - - Table of contents - ----------------- - .. toctree:: :maxdepth: 3 :includehidden: + Yosys (index) introduction + getting_started/index using_yosys/index yosys_internals/index - appendix +.. toctree:: + :caption: Appendix + :titlesonly: + :includehidden: + + appendix/primer + appendix/rtlil_text + appendix/auxlibs + appendix/auxprogs + + bib + + cell_index + cmd_ref diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 1d9cd0080..376c8043b 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -69,9 +69,14 @@ Things you can't do - Check out `nextpnr`_ for that +- Rely on built-in syntax checking + + - Use an external tool like `verilator`_ instead + .. todo:: nextpnr for FPGAs, consider mentioning openlane, vpr, coriolis .. _nextpnr: https://github.com/YosysHQ/nextpnr +.. _verilator: https://www.veripool.org/verilator/ The Yosys family ---------------- @@ -161,9 +166,9 @@ Benefits of open source HDL synthesis - Cost (also applies to ``free as in free beer`` solutions): - Today the cost for a mask set in 180nm technology is far less than - the cost for the design tools needed to design the mask layouts. Open Source - ASIC flows are an important enabler for ASIC-level Open Source Hardware. + Today the cost for a mask set in 180nm technology is far less than the cost + for the design tools needed to design the mask layouts. Open Source ASIC flows + are an important enabler for ASIC-level Open Source Hardware. - Availability and Reproducibility: @@ -171,21 +176,23 @@ Benefits of open source HDL synthesis else can also use. Even if most universities have access to all major commercial tools, you usually do not have easy access to the version that was used in a research project a couple of years ago. With Open Source tools you - can even release the source code of the tool you have used alongside your data. + can even release the source code of the tool you have used alongside your + data. - Framework: - Yosys is not only a tool. It is a framework that can be used as basis for other - developments, so researchers and hackers alike do not need to re-invent the - basic functionality. Extensibility was one of Yosys' design goals. + Yosys is not only a tool. It is a framework that can be used as basis for + other developments, so researchers and hackers alike do not need to re-invent + the basic functionality. Extensibility was one of Yosys' design goals. - All-in-one: - Because of the framework characteristics of Yosys, an increasing number of features - become available in one tool. Yosys not only can be used for circuit synthesis but - also for formal equivalence checking, SAT solving, and for circuit analysis, to - name just a few other application domains. With proprietary software one needs to - learn a new tool for each of these applications. + Because of the framework characteristics of Yosys, an increasing number of + features become available in one tool. Yosys not only can be used for circuit + synthesis but also for formal equivalence checking, SAT solving, and for + circuit analysis, to name just a few other application domains. With + proprietary software one needs to learn a new tool for each of these + applications. - Educational Tool: diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt index dbba55832..203205169 100644 --- a/docs/source/requirements.txt +++ b/docs/source/requirements.txt @@ -1,3 +1,3 @@ -furo +furo-ys @ git+https://github.com/YosysHQ/furo-ys sphinxcontrib-bibtex rtds-action diff --git a/docs/source/using_yosys/more_scripting/data_flow_tracking.rst b/docs/source/using_yosys/more_scripting/data_flow_tracking.rst new file mode 100644 index 000000000..aa13a2e69 --- /dev/null +++ b/docs/source/using_yosys/more_scripting/data_flow_tracking.rst @@ -0,0 +1,114 @@ +Dataflow tracking +------------------- + +Yosys can be used to answer questions such as "can this signal affect this other +signal?" via its *dataflow tracking* support. For this, four special cells, +`$get_tag`, `$set_tag`, `$overwrite_tag` and `$original_tag` are inserted into +the design (e.g. by a custom Yosys pass) and then the `dft_tag` is run, which +converts these cells into ordinary logic. Typically, one would then use `SBY`_ +to prove assertions involving these cells. + +.. _SBY: https://yosyshq.readthedocs.io/projects/sby + +Ordinarily in Yosys, the state of a bit is simply ``0`` or ``1`` (or one of the +special values, ``z`` and ``x``). During dataflow tracking they are augmented +with a set of tags. For example, the state of a bit could be ``0`` and the set +of tags ``"KEY"`` and ``"OVERFLOW"``. + +In addition to their usual operations on the logical bits, Yosys operations must +now also process the status of the tags. For this, tags are simply *forwarded* +or *propagated* (i.e. copied) from inputs to outputs, according to the following +general rule: + + A tag is forwarded from an input to an output if the input can affect the + output, for that particular state of all other inputs. + +For example, XOR, AND and OR cells propagate tags as follows: + +#. XOR simply forwards all tags from its inputs to its output, because inputs to + XOR can always affect the output. +#. AND forwards tags on a given input only if the other input is ``1``. Because + if one input is ``0``, the other input can never affect the output. +#. Similarly, OR forwards tags only if the other input is ``0``. + +There are two exceptions to this rule: + +#. In general, propagation is only determined approximately. For example, unless + the ``dft_tag`` code knows about a cell, it simply assumes the worst-case + behaviour that all inputs can affect all outputs. Further, the code also does + not consider that, when a signal affects multiple inputs of a cell, the + resulting simultaneous changes of the inputs can cancel each other out, for + example ``A ^ A`` or ``A ^ (B ^ A)`` is independent of ``A``, but its tags + would be propagated nonetheless. +#. If tag groups are used, the rules are modified (see below). + +Because of this propagation behaviour, we can answer questions about what +signals are affected by a certain signal, by injecting a tag at that point in +the circuit, and observing where the tag is visible. + +Example use cases +~~~~~~~~~~~~~~~~~~ + +As an example use case, consider a cryptographic processor which is not supposed +to expose its secret keys to the outside world. We can tag all key bits with the +``"KEY"`` tag and use `SBY`_ to formally verify that no external signal ever +carries the ``"KEY"`` tag, meaning that key information is not visible to the +outside. As a caveat, we have to manually clear the ``"KEY"`` tag during +cryptographic operations, as proving that the cryptographic operations +themselves do not leak key information is beyond the ability of Yosys. However +we can still easily detect, if e.g. an engineer forgot to remove debugging code +that allows reading back key data. + +As a different use case, we can modify all adders in the design to set the +``"OVERFLOW"`` tag on their output bits, if the addition overflowed, and then +add asserts to all flip-flop inputs and output signals that they do not carry +the ``"OVERFLOW"`` tag, i.e. that the results of overflowed additions never +affect system state. Note that in this particular example we use the ability of +tag insertion to be conditional on logic, in this case the overflow condition of +an adder. + +Semantics of dataflow tracking cells +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``$set_tag`` has inputs ``A``, ``SET``, ``CLR``, an output ``Y`` and a string +parameter ``TAG``. The logic value of ``A`` and all tags other than the one +named by the ``TAG`` parameter are simply copied to ``Y``. If ``SET`` is ``1``, +then the named tag is added to ``Y``. Otherwise, if ``CLR`` is ``1``, then the +named tag is removed. Otherwise, the tag is unchanged, i.e. it is present in +``Y`` if it is present in ``A``. + +``$get_tag`` has an input ``A`` and an output ``Y`` and a string parameter +``TAG``. ``$get_tag`` inspects ``A`` for the presence or absence of a tag of the +given name and sets ``Y`` to ``1`` if the tag is present. The logical value of +``A`` is completely ignored. + +``$overwrite_tag`` functions like ``$set_tag``, but lacks the ``Y`` output. +Instead of providing a modified version of the input signal, it modifies the +signal ``A`` "in-place", i.e. if a signal is input to ``$overwrite_tag``, that +is equivalent to interposing a ``$set_tag`` between its driver and all cells it +is connected to. The main purpose of ``$overwrite_tag`` is adding tags to +signals produced within a module that cannot or should not be modified itself. + +``$original_tag`` functions identically to ``$get_tag``, but ignores +``$overwrite_tag``, i.e. when converting the ``$overwrite_tag`` to ``$set_tag`` +as described above, it is equivalent to inserting the ``$get_tag`` *before* the +``$set_tag``. + +Tag groups +~~~~~~~~~~~~~~ + +Tag groups are an advanced feature that modify the propagation rule discussed +above. To use tag groups, simply name tags according to the schema +``"group:name"``. For example, ``"key:0"``, ``"key:a"``, ``"key:b"`` would be +three tags in the ``"key"`` group. + +The propagation rule is then amended by + + Inputs cannot block the propagation of each other's tags for tags of the same + group. + +For example, an AND gate will propagate a given tag on one input, if the other +input is either 1 or carries a tag of the same group. So if one input is ``0, +"key:a"`` and the other is ``0, "key:b"`` the result would be ``0, "key:a", +"key:b"``, rather than simply ``0``. Note that if we add an unrelated +``"overflow"`` tag to the first input, it would still not be propagated. \ No newline at end of file diff --git a/docs/source/using_yosys/more_scripting/index.rst b/docs/source/using_yosys/more_scripting/index.rst index 090b9e0b9..6265e5d0e 100644 --- a/docs/source/using_yosys/more_scripting/index.rst +++ b/docs/source/using_yosys/more_scripting/index.rst @@ -12,5 +12,6 @@ More scripting selections interactive_investigation model_checking + data_flow_tracking .. troubleshooting diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst index 03a1faefa..e9c9bc9ac 100644 --- a/docs/source/using_yosys/more_scripting/interactive_investigation.rst +++ b/docs/source/using_yosys/more_scripting/interactive_investigation.rst @@ -13,9 +13,9 @@ A look at the show command .. TODO:: merge into :doc:`/getting_started/scripting_intro` show section -This section explores the :cmd:ref:`show` command and explains the symbols used -in the circuit diagrams generated by it. The code used is included in the Yosys -code base under |code_examples/show|_. +This section explores the `show` command and explains the symbols used in the +circuit diagrams generated by it. The code used is included in the Yosys code +base under |code_examples/show|_. .. |code_examples/show| replace:: :file:`docs/source/code_examples/show` .. _code_examples/show: https://github.com/YosysHQ/yosys/tree/main/docs/source/code_examples/show @@ -24,7 +24,7 @@ A simple circuit ^^^^^^^^^^^^^^^^ :ref:`example_v` below provides the Verilog code for a simple circuit which we -will use to demonstrate the usage of :cmd:ref:`show` in a simple setting. +will use to demonstrate the usage of `show` in a simple setting. .. literalinclude:: /code_examples/show/example.v :language: Verilog @@ -32,11 +32,10 @@ will use to demonstrate the usage of :cmd:ref:`show` in a simple setting. :name: example_v The Yosys synthesis script we will be running is included as -:numref:`example_ys`. Note that :cmd:ref:`show` is called with the ``-pause`` -option, that halts execution of the Yosys script until the user presses the -Enter key. Using :yoscrypt:`show -pause` also allows the user to enter an -interactive shell to further investigate the circuit before continuing -synthesis. +:numref:`example_ys`. Note that `show` is called with the ``-pause`` option, +that halts execution of the Yosys script until the user presses the Enter key. +Using :yoscrypt:`show -pause` also allows the user to enter an interactive shell +to further investigate the circuit before continuing synthesis. .. literalinclude:: /code_examples/show/example_show.ys :language: yoscrypt @@ -58,7 +57,7 @@ is shown. .. figure:: /_images/code_examples/show/example_first.* :class: width-helper invert-helper - Output of the first :cmd:ref:`show` command in :numref:`example_ys` + Output of the first `show` command in :numref:`example_ys` The first output shows the design directly after being read by the Verilog front-end. Input and output ports are displayed as octagonal shapes. Cells are @@ -66,7 +65,7 @@ displayed as rectangles with inputs on the left and outputs on the right side. The cell labels are two lines long: The first line contains a unique identifier for the cell and the second line contains the cell type. Internal cell types are prefixed with a dollar sign. For more details on the internal cell library, see -:doc:`/yosys_internals/formats/cell_library`. +:doc:`/cell_index`. Constants are shown as ellipses with the constant value as label. The syntax ``'`` is used for constants that are not 32-bit wide and/or @@ -74,50 +73,50 @@ contain bits that are not 0 or 1 (i.e. ``x`` or ``z``). Ordinary 32-bit constants are written using decimal numbers. Single-bit signals are shown as thin arrows pointing from the driver to the -load. Signals that are multiple bits wide are shown as think arrows. +load. Signals that are multiple bits wide are shown as thick arrows. Finally *processes* are shown in boxes with round corners. Processes are Yosys' internal representation of the decision-trees and synchronization events modelled in a Verilog ``always``-block. The label reads ``PROC`` followed by a unique identifier in the first line and contains the source code location of the original ``always``-block in the second line. Note how the multiplexer from the -``?:``-expression is represented as a ``$mux`` cell but the multiplexer from the +``?:``-expression is represented as a `$mux` cell but the multiplexer from the ``if``-statement is yet still hidden within the process. -The :cmd:ref:`proc` command transforms the process from the first diagram into a +The `proc` command transforms the process from the first diagram into a multiplexer and a d-type flip-flop, which brings us to the second diagram: .. figure:: /_images/code_examples/show/example_second.* :class: width-helper invert-helper - Output of the second :cmd:ref:`show` command in :numref:`example_ys` + Output of the second `show` command in :numref:`example_ys` The Rhombus shape to the right is a dangling wire. (Wire nodes are only shown if they are dangling or have "public" names, for example names assigned from the Verilog input.) Also note that the design now contains two instances of a -``BUF``-node. These are artefacts left behind by the :cmd:ref:`proc` command. It -is quite usual to see such artefacts after calling commands that perform changes -in the design, as most commands only care about doing the transformation in the -least complicated way, not about cleaning up after them. The next call to -:cmd:ref:`clean` (or :cmd:ref:`opt`, which includes :cmd:ref:`clean` as one of -its operations) will clean up these artefacts. This operation is so common in -Yosys scripts that it can simply be abbreviated with the ``;;`` token, which -doubles as separator for commands. Unless one wants to specifically analyze this -artefacts left behind some operations, it is therefore recommended to always -call :cmd:ref:`clean` before calling :cmd:ref:`show`. +``BUF``-node. These are artefacts left behind by the `proc` command. It is quite +usual to see such artefacts after calling commands that perform changes in the +design, as most commands only care about doing the transformation in the least +complicated way, not about cleaning up after them. The next call to `clean` (or +`opt`, which includes `clean` as one of its operations) will clean up these +artefacts. This operation is so common in Yosys scripts that it can simply be +abbreviated with the ``;;`` token, which doubles as separator for commands. +Unless one wants to specifically analyze this artefacts left behind some +operations, it is therefore recommended to always call `clean` before calling +`show`. -In this script we directly call :cmd:ref:`opt` as the next step, which finally -leads us to the third diagram: +In this script we directly call `opt` as the next step, which finally leads us +to the third diagram: .. figure:: /_images/code_examples/show/example_third.* :class: width-helper invert-helper :name: example_out - Output of the third :cmd:ref:`show` command in :ref:`example_ys` + Output of the third `show` command in :ref:`example_ys` -Here we see that the :cmd:ref:`opt` command not only has removed the artifacts -left behind by :cmd:ref:`proc`, but also determined correctly that it can remove -the first ``$mux`` cell without changing the behavior of the circuit. +Here we see that the `opt` command not only has removed the artifacts left +behind by `proc`, but also determined correctly that it can remove the first +`$mux` cell without changing the behavior of the circuit. Break-out boxes for signal vectors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -129,7 +128,7 @@ accesses. :caption: :file:`splice.v` :name: splice_src -Notice how the output for this circuit from the :cmd:ref:`show` command +Notice how the output for this circuit from the `show` command (:numref:`splice_dia`) appears quite complex. This is an unfortunate side effect of the way Yosys handles signal vectors (aka. multi-bit wires or buses) as native objects. While this provides great advantages when analyzing circuits @@ -169,7 +168,7 @@ mapped to a cell library: :name: first_pitfall A half-adder built from simple CMOS gates, demonstrating common pitfalls when - using :cmd:ref:`show` + using `show` .. literalinclude:: /code_examples/show/cmos.ys :language: yoscrypt @@ -188,8 +187,8 @@ individual bits, resulting in an unnecessary complex diagram. :class: width-helper invert-helper :name: second_pitfall - Effects of :cmd:ref:`splitnets` command and of providing a cell library on - design in :numref:`first_pitfall` + Effects of `splitnets` command and of providing a cell library on design in + :numref:`first_pitfall` .. literalinclude:: /code_examples/show/cmos.ys :language: yoscrypt @@ -201,11 +200,11 @@ individual bits, resulting in an unnecessary complex diagram. For :numref:`second_pitfall`, Yosys has been given a description of the cell library as Verilog file containing blackbox modules. There are two ways to load cell descriptions into Yosys: First the Verilog file for the cell library can be -passed directly to the :cmd:ref:`show` command using the ``-lib `` -option. Secondly it is possible to load cell libraries into the design with the +passed directly to the `show` command using the ``-lib `` option. +Secondly it is possible to load cell libraries into the design with the :yoscrypt:`read_verilog -lib ` command. The second method has the great advantage that the library only needs to be loaded once and can then be -used in all subsequent calls to the :cmd:ref:`show` command. +used in all subsequent calls to the `show` command. In addition to that, :numref:`second_pitfall` was generated after :yoscrypt:`splitnet -ports` was run on the design. This command splits all @@ -216,22 +215,22 @@ module ports. Per default the command only operates on interior signals. Miscellaneous notes ^^^^^^^^^^^^^^^^^^^ -Per default the :cmd:ref:`show` command outputs a temporary dot file and -launches ``xdot`` to display it. The options ``-format``, ``-viewer`` and -``-prefix`` can be used to change format, viewer and filename prefix. Note that -the ``pdf`` and ``ps`` format are the only formats that support plotting -multiple modules in one run. The ``dot`` format can be used to output multiple -modules, however ``xdot`` will raise an error when trying to read them. +Per default the `show` command outputs a temporary dot file and launches +``xdot`` to display it. The options ``-format``, ``-viewer`` and ``-prefix`` can +be used to change format, viewer and filename prefix. Note that the ``pdf`` and +``ps`` format are the only formats that support plotting multiple modules in one +run. The ``dot`` format can be used to output multiple modules, however +``xdot`` will raise an error when trying to read them. In densely connected circuits it is sometimes hard to keep track of the -individual signal wires. For these cases it can be useful to call -:cmd:ref:`show` with the ``-colors `` argument, which randomly assigns -colors to the nets. The integer (> 0) is used as seed value for the random color -assignments. Sometimes it is necessary it try some values to find an assignment -of colors that looks good. +individual signal wires. For these cases it can be useful to call `show` with +the ``-colors `` argument, which randomly assigns colors to the nets. +The integer (> 0) is used as seed value for the random color assignments. +Sometimes it is necessary it try some values to find an assignment of colors +that looks good. The command :yoscrypt:`help show` prints a complete listing of all options -supported by the :cmd:ref:`show` command. +supported by the `show` command. Navigating the design ~~~~~~~~~~~~~~~~~~~~~ @@ -244,10 +243,10 @@ relevant portions of the circuit. In addition to *what* to display one also needs to carefully decide *when* to display it, with respect to the synthesis flow. In general it is a good idea to troubleshoot a circuit in the earliest state in which a problem can be -reproduced. So if, for example, the internal state before calling the -:cmd:ref:`techmap` command already fails to verify, it is better to troubleshoot -the coarse-grain version of the circuit before :cmd:ref:`techmap` than the -gate-level circuit after :cmd:ref:`techmap`. +reproduced. So if, for example, the internal state before calling the `techmap` +command already fails to verify, it is better to troubleshoot the coarse-grain +version of the circuit before `techmap` than the gate-level circuit after +`techmap`. .. Note:: @@ -260,31 +259,29 @@ Interactive navigation ^^^^^^^^^^^^^^^^^^^^^^ Once the right state within the synthesis flow for debugging the circuit has -been identified, it is recommended to simply add the :cmd:ref:`shell` command to -the matching place in the synthesis script. This command will stop the synthesis -at the specified moment and go to shell mode, where the user can interactively +been identified, it is recommended to simply add the `shell` command to the +matching place in the synthesis script. This command will stop the synthesis at +the specified moment and go to shell mode, where the user can interactively enter commands. For most cases, the shell will start with the whole design selected (i.e. when -the synthesis script does not already narrow the selection). The command -:cmd:ref:`ls` can now be used to create a list of all modules. The command -:cmd:ref:`cd` can be used to switch to one of the modules (type ``cd ..`` to -switch back). Now the :cmd:ref:`ls` command lists the objects within that -module. This is demonstrated below using :file:`example.v` from `A simple -circuit`_: +the synthesis script does not already narrow the selection). The command `ls` +can now be used to create a list of all modules. The command `cd` can be used to +switch to one of the modules (type ``cd ..`` to switch back). Now the `ls` +command lists the objects within that module. This is demonstrated below using +:file:`example.v` from `A simple circuit`_: .. literalinclude:: /code_examples/show/example.out :language: doscon :start-at: yosys> ls :end-before: yosys [example]> dump - :caption: Output of :cmd:ref:`ls` and :cmd:ref:`cd` after running :file:`yosys example.v` + :caption: Output of `ls` and `cd` after running :file:`yosys example.v` :name: lscd -When a module is selected using the :cmd:ref:`cd` command, all commands (with a -few exceptions, such as the ``read_`` and ``write_`` commands) operate only on -the selected module. This can also be useful for synthesis scripts where -different synthesis strategies should be applied to different modules in the -design. +When a module is selected using the `cd` command, all commands (with a few +exceptions, such as the ``read_`` and ``write_`` commands) operate only on the +selected module. This can also be useful for synthesis scripts where different +synthesis strategies should be applied to different modules in the design. We can see that the cell names from :numref:`example_out` are just abbreviations of the actual cell names, namely the part after the last dollar-sign. Most @@ -292,15 +289,14 @@ auto-generated names (the ones starting with a dollar sign) are rather long and contains some additional information on the origin of the named object. But in most cases those names can simply be abbreviated using the last part. -Usually all interactive work is done with one module selected using the -:cmd:ref:`cd` command. But it is also possible to work from the design-context -(``cd ..``). In this case all object names must be prefixed with -``/``. For example ``a*/b*`` would refer to all objects whose names -start with ``b`` from all modules whose names start with ``a``. +Usually all interactive work is done with one module selected using the `cd` +command. But it is also possible to work from the design-context (``cd ..``). In +this case all object names must be prefixed with ``/``. For example +``a*/b*`` would refer to all objects whose names start with ``b`` from all +modules whose names start with ``a``. -The :cmd:ref:`dump` command can be used to print all information about an -object. For example, calling :yoscrypt:`dump $2` after the :yoscrypt:`cd -example` above: +The `dump` command can be used to print all information about an object. For +example, calling :yoscrypt:`dump $2` after the :yoscrypt:`cd example` above: .. literalinclude:: /code_examples/show/example.out :language: RTLIL @@ -323,11 +319,10 @@ tools). - The selection mechanism, especially patterns such as ``%ci`` and ``%co``, can be used to figure out how parts of the design are connected. -- Commands such as :cmd:ref:`submod`, :cmd:ref:`expose`, and :cmd:ref:`splice` - can be used to transform the design into an equivalent design that is easier - to analyse. -- Commands such as :cmd:ref:`eval` and :cmd:ref:`sat` can be used to investigate - the behavior of the circuit. +- Commands such as `submod`, `expose`, and `splice` can be used to transform the + design into an equivalent design that is easier to analyse. +- Commands such as `eval` and `sat` can be used to investigate the behavior of + the circuit. - :doc:`/cmd/show`. - :doc:`/cmd/dump`. - :doc:`/cmd/add` and :doc:`/cmd/delete` can be used to modify and reorganize a @@ -342,10 +337,10 @@ The code used is included in the Yosys code base under Changing design hierarchy ^^^^^^^^^^^^^^^^^^^^^^^^^ -Commands such as :cmd:ref:`flatten` and :cmd:ref:`submod` can be used to change -the design hierarchy, i.e. flatten the hierarchy or moving parts of a module to -a submodule. This has applications in synthesis scripts as well as in reverse -engineering and analysis. An example using :cmd:ref:`submod` is shown below for +Commands such as `flatten` and `submod` can be used to change the design +hierarchy, i.e. flatten the hierarchy or moving parts of a module to a +submodule. This has applications in synthesis scripts as well as in reverse +engineering and analysis. An example using `submod` is shown below for reorganizing a module in Yosys and checking the resulting circuit. .. literalinclude:: /code_examples/scrambler/scrambler.v @@ -388,10 +383,10 @@ Analyzing the resulting circuit with :doc:`/cmd/eval`: Behavioral changes ^^^^^^^^^^^^^^^^^^ -Commands such as :cmd:ref:`techmap` can be used to make behavioral changes to -the design, for example changing asynchronous resets to synchronous resets. This -has applications in design space exploration (evaluation of various -architectures for one circuit). +Commands such as `techmap` can be used to make behavioral changes to the design, +for example changing asynchronous resets to synchronous resets. This has +applications in design space exploration (evaluation of various architectures +for one circuit). The following techmap map file replaces all positive-edge async reset flip-flops with positive-edge sync reset flip-flops. The code is taken from the example @@ -425,7 +420,7 @@ Yosys script for ASIC synthesis of the Amber ARMv2 CPU. endmodule -For more on the :cmd:ref:`techmap` command, see the page on +For more on the `techmap` command, see the page on :doc:`/yosys_internals/techmap`. Advanced investigation techniques @@ -448,12 +443,12 @@ Recall the ``memdemo`` design from :ref:`advanced_logic_cones`: Because this produces a rather large circuit, it can be useful to split it into smaller parts for viewing and working with. :numref:`submod` does exactly that, -utilising the :cmd:ref:`submod` command to split the circuit into three -sections: ``outstage``, ``selstage``, and ``scramble``. +utilising the `submod` command to split the circuit into three sections: +``outstage``, ``selstage``, and ``scramble``. .. literalinclude:: /code_examples/selections/submod.ys :language: yoscrypt - :caption: Using :cmd:ref:`submod` to break up the circuit from :file:`memdemo.v` + :caption: Using `submod` to break up the circuit from :file:`memdemo.v` :start-after: cd memdemo :end-before: cd .. :name: submod @@ -481,9 +476,9 @@ below. Evaluation of combinatorial circuits ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The :cmd:ref:`eval` command can be used to evaluate combinatorial circuits. As -an example, we will use the ``selstage`` subnet of ``memdemo`` which we found -above and is shown in :numref:`selstage`. +The `eval` command can be used to evaluate combinatorial circuits. As an +example, we will use the ``selstage`` subnet of ``memdemo`` which we found above +and is shown in :numref:`selstage`. .. todo:: replace inline code @@ -526,21 +521,21 @@ The ``-table`` option can be used to create a truth table. For example: Assumed undef (x) value for the following signals: \s2 -Note that the :cmd:ref:`eval` command (as well as the :cmd:ref:`sat` command -discussed in the next sections) does only operate on flattened modules. It can -not analyze signals that are passed through design hierarchy levels. So the -:cmd:ref:`flatten` command must be used on modules that instantiate other -modules before these commands can be applied. +Note that the `eval` command (as well as the `sat` command discussed in the next +sections) does only operate on flattened modules. It can not analyze signals +that are passed through design hierarchy levels. So the `flatten` command must +be used on modules that instantiate other modules before these commands can be +applied. Solving combinatorial SAT problems ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Often the opposite of the :cmd:ref:`eval` command is needed, i.e. the circuits -output is given and we want to find the matching input signals. For small -circuits with only a few input bits this can be accomplished by trying all -possible input combinations, as it is done by the ``eval -table`` command. For -larger circuits however, Yosys provides the :cmd:ref:`sat` command that uses a -`SAT`_ solver, `MiniSAT`_, to solve this kind of problems. +Often the opposite of the `eval` command is needed, i.e. the circuits output is +given and we want to find the matching input signals. For small circuits with +only a few input bits this can be accomplished by trying all possible input +combinations, as it is done by the ``eval -table`` command. For larger circuits +however, Yosys provides the `sat` command that uses a `SAT`_ solver, `MiniSAT`_, +to solve this kind of problems. .. _SAT: http://en.wikipedia.org/wiki/Circuit_satisfiability @@ -551,9 +546,9 @@ larger circuits however, Yosys provides the :cmd:ref:`sat` command that uses a While it is possible to perform model checking directly in Yosys, it is highly recommended to use SBY or EQY for formal hardware verification. -The :cmd:ref:`sat` command works very similar to the :cmd:ref:`eval` command. -The main difference is that it is now also possible to set output values and -find the corresponding input values. For Example: +The `sat` command works very similar to the `eval` command. The main difference +is that it is now also possible to set output values and find the corresponding +input values. For Example: .. todo:: replace inline code @@ -580,8 +575,8 @@ find the corresponding input values. For Example: \s1 0 0 00 \s2 0 0 00 -Note that the :cmd:ref:`sat` command supports signal names in both arguments to -the ``-set`` option. In the above example we used ``-set s1 s2`` to constraint +Note that the `sat` command supports signal names in both arguments to the +``-set`` option. In the above example we used ``-set s1 s2`` to constraint ``s1`` and ``s2`` to be equal. When more complex constraints are needed, a wrapper circuit must be constructed that checks the constraints and signals if the constraint was met using an extra output port, which then can be forced to a @@ -642,8 +637,8 @@ of course be to perform the test in 32 bits, for example by replacing ``p != a*b`` in the miter with ``p != {16'd0,a}b``, or by using a temporary variable for the 32 bit product ``a*b``. But as 31 fits well into 8 bits (and as the purpose of this document is to show off Yosys features) we can also simply force -the upper 8 bits of ``a`` and ``b`` to zero for the :cmd:ref:`sat` call, as is -done below. +the upper 8 bits of ``a`` and ``b`` to zero for the `sat` call, as is done +below. .. todo:: replace inline code @@ -705,18 +700,18 @@ command: sat -seq 6 -show y -show d -set-init-undef \ -max_undef -set-at 4 y 1 -set-at 5 y 2 -set-at 6 y 3 -The ``-seq 6`` option instructs the :cmd:ref:`sat` command to solve a sequential -problem in 6 time steps. (Experiments with lower number of steps have show that -at least 3 cycles are necessary to bring the circuit in a state from which the -sequence 1, 2, 3 can be produced.) +The ``-seq 6`` option instructs the `sat` command to solve a sequential problem +in 6 time steps. (Experiments with lower number of steps have show that at least +3 cycles are necessary to bring the circuit in a state from which the sequence +1, 2, 3 can be produced.) -The ``-set-init-undef`` option tells the :cmd:ref:`sat` command to initialize -all registers to the undef (``x``) state. The way the ``x`` state is treated in +The ``-set-init-undef`` option tells the `sat` command to initialize all +registers to the undef (``x``) state. The way the ``x`` state is treated in Verilog will ensure that the solution will work for any initial state. -The ``-max_undef`` option instructs the :cmd:ref:`sat` command to find a -solution with a maximum number of undefs. This way we can see clearly which -inputs bits are relevant to the solution. +The ``-max_undef`` option instructs the `sat` command to find a solution with a +maximum number of undefs. This way we can see clearly which inputs bits are +relevant to the solution. Finally the three ``-set-at`` options add constraints for the ``y`` signal to play the 1, 2, 3 sequence, starting with time step 4. @@ -807,7 +802,7 @@ is the only way of setting the ``s1`` and ``s2`` registers to a known value. The input values for the other steps are a bit harder to work out manually, but the SAT solver finds the correct solution in an instant. -There is much more to write about the :cmd:ref:`sat` command. For example, there -is a set of options that can be used to performs sequential proofs using -temporal induction :cite:p:`een2003temporal`. The command ``help sat`` can be -used to print a list of all options with short descriptions of their functions. +There is much more to write about the `sat` command. For example, there is a set +of options that can be used to performs sequential proofs using temporal +induction :cite:p:`een2003temporal`. The command ``help sat`` can be used to +print a list of all options with short descriptions of their functions. diff --git a/docs/source/using_yosys/more_scripting/model_checking.rst b/docs/source/using_yosys/more_scripting/model_checking.rst index 92a9d85ce..799c99b6f 100644 --- a/docs/source/using_yosys/more_scripting/model_checking.rst +++ b/docs/source/using_yosys/more_scripting/model_checking.rst @@ -17,8 +17,7 @@ passes in Yosys. Other applications include checking if a module conforms to interface standards. -The :cmd:ref:`sat` command in Yosys can be used to perform Symbolic Model -Checking. +The `sat` command in Yosys can be used to perform Symbolic Model Checking. Checking techmap ~~~~~~~~~~~~~~~~ diff --git a/docs/source/using_yosys/more_scripting/selections.rst b/docs/source/using_yosys/more_scripting/selections.rst index b00283474..e82f23497 100644 --- a/docs/source/using_yosys/more_scripting/selections.rst +++ b/docs/source/using_yosys/more_scripting/selections.rst @@ -9,33 +9,33 @@ The selection framework .. todo:: reduce overlap with :doc:`/getting_started/scripting_intro` select section -The :cmd:ref:`select` command can be used to create a selection for subsequent -commands. For example: +The `select` command can be used to create a selection for subsequent commands. +For example: .. code:: yoscrypt select foobar # select the module foobar delete # delete selected objects -Normally the :cmd:ref:`select` command overwrites a previous selection. The -commands :yoscrypt:`select -add` and :yoscrypt:`select -del` can be used to add -or remove objects from the current selection. +Normally the `select` command overwrites a previous selection. The commands +:yoscrypt:`select -add` and :yoscrypt:`select -del` can be used to add or remove +objects from the current selection. The command :yoscrypt:`select -clear` can be used to reset the selection to the default, which is a complete selection of everything in the current module. This selection framework can also be used directly in many other commands. Whenever a command has ``[selection]`` as last argument in its usage help, this -means that it will use the engine behind the :cmd:ref:`select` command to -evaluate additional arguments and use the resulting selection instead of the -selection created by the last :cmd:ref:`select` command. +means that it will use the engine behind the `select` command to evaluate +additional arguments and use the resulting selection instead of the selection +created by the last `select` command. -For example, the command :cmd:ref:`delete` will delete everything in the current +For example, the command `delete` will delete everything in the current selection; while :yoscrypt:`delete foobar` will only delete the module foobar. -If no :cmd:ref:`select` command has been made, then the "current selection" will -be the whole design. +If no `select` command has been made, then the "current selection" will be the +whole design. -.. note:: Many of the examples on this page make use of the :cmd:ref:`show` +.. note:: Many of the examples on this page make use of the `show` command to visually demonstrate the effect of selections. For a more detailed look at this command, refer to :ref:`interactive_show`. @@ -59,8 +59,8 @@ Module and design context ^^^^^^^^^^^^^^^^^^^^^^^^^ Commands can be executed in *module/* or *design/* context. Until now, all -commands have been executed in design context. The :cmd:ref:`cd` command can be -used to switch to module context. +commands have been executed in design context. The `cd` command can be used to +switch to module context. In module context, all commands only effect the active module. Objects in the module are selected without the ``/`` prefix. For example: @@ -91,7 +91,7 @@ Special patterns can be used to select by object property or type. For example: a:foobar=42` - select all modules with the attribute ``blabla`` set: :yoscrypt:`select A:blabla` -- select all $add cells from the module foo: :yoscrypt:`select foo/t:$add` +- select all `$add` cells from the module foo: :yoscrypt:`select foo/t:$add` A complete list of pattern expressions can be found in :doc:`/cmd/select`. @@ -101,12 +101,12 @@ Operations on selections Combining selections ^^^^^^^^^^^^^^^^^^^^ -The :cmd:ref:`select` command is actually much more powerful than it might seem -at first glance. When it is called with multiple arguments, each argument is -evaluated and pushed separately on a stack. After all arguments have been -processed it simply creates the union of all elements on the stack. So -:yoscrypt:`select t:$add a:foo` will select all ``$add`` cells and all objects -with the ``foo`` attribute set: +The `select` command is actually much more powerful than it might seem at first +glance. When it is called with multiple arguments, each argument is evaluated +and pushed separately on a stack. After all arguments have been processed it +simply creates the union of all elements on the stack. So :yoscrypt:`select +t:$add a:foo` will select all `$add` cells and all objects with the ``foo`` +attribute set: .. literalinclude:: /code_examples/selections/foobaraddsub.v :caption: Test module for operations on selections @@ -126,7 +126,7 @@ ineffective way of selecting the interesting part of the design. Special arguments can be used to combine the elements on the stack. For example the ``%i`` arguments pops the last two elements from the stack, intersects them, and pushes the result back on the stack. So :yoscrypt:`select t:$add a:foo %i` will -select all ``$add`` cells that have the ``foo`` attribute set: +select all `$add` cells that have the ``foo`` attribute set: .. code-block:: :caption: Output for command ``select t:$add a:foo %i -list`` on :numref:`foobaraddsub` @@ -190,7 +190,7 @@ Selecting logic cones :numref:`sumprod_01` shows what is called the ``input cone`` of ``sum``, i.e. all cells and signals that are used to generate the signal ``sum``. The ``%ci`` action can be used to select the input cones of all object in the top selection -in the stack maintained by the :cmd:ref:`select` command. +in the stack maintained by the `select` command. As with the ``%x`` action, these commands broaden the selection by one "step". But this time the operation only works against the direction of data flow. That @@ -220,11 +220,11 @@ The following sequence of diagrams demonstrates this step-wise expansion: Output of :yoscrypt:`show prod %ci %ci %ci` on :numref:`sumprod` Notice the subtle difference between :yoscrypt:`show prod %ci` and -:yoscrypt:`show prod %ci %ci`. Both images show the ``$mul`` cell driven by -some inputs ``$3_Y`` and ``c``. However it is not until the second image, -having called ``%ci`` the second time, that :cmd:ref:`show` is able to -distinguish between ``$3_Y`` being a wire and ``c`` being an input. We can see -this better with the :cmd:ref:`dump` command instead: +:yoscrypt:`show prod %ci %ci`. Both images show the `$mul` cell driven by some +inputs ``$3_Y`` and ``c``. However it is not until the second image, having +called ``%ci`` the second time, that `show` is able to distinguish between +``$3_Y`` being a wire and ``c`` being an input. We can see this better with the +`dump` command instead: .. literalinclude:: /code_examples/selections/sumprod.out :language: RTLIL @@ -241,8 +241,8 @@ be a bit dull. So there is a shortcut for that: the number of iterations can be appended to the action. So for example the action ``%ci3`` is identical to performing the ``%ci`` action three times. -The action ``%ci*`` performs the ``%ci`` action over and over again until it -has no effect anymore. +The action ``%ci*`` performs the ``%ci`` action over and over again until it has +no effect anymore. .. _advanced_logic_cones: @@ -264,8 +264,8 @@ source repository. :name: memdemo_src :language: verilog -The script :file:`memdemo.ys` is used to generate the images included here. Let's -look at the first section: +The script :file:`memdemo.ys` is used to generate the images included here. +Let's look at the first section: .. literalinclude:: /code_examples/selections/memdemo.ys :caption: Synthesizing :ref:`memdemo_src` @@ -276,8 +276,8 @@ look at the first section: This loads :numref:`memdemo_src` and synthesizes the included module. Note that this code can be copied and run directly in a Yosys command line session, provided :file:`memdemo.v` is in the same directory. We can now change to the -``memdemo`` module with ``cd memdemo``, and call :cmd:ref:`show` to see the -diagram in :numref:`memdemo_00`. +``memdemo`` module with ``cd memdemo``, and call `show` to see the diagram in +:numref:`memdemo_00`. .. figure:: /_images/code_examples/selections/memdemo_00.* :class: width-helper invert-helper @@ -296,7 +296,7 @@ cones`_ from above, we can use :yoscrypt:`show y %ci2`: Output of :yoscrypt:`show y %ci2` -From this we would learn that ``y`` is driven by a ``$dff cell``, that ``y`` is +From this we would learn that ``y`` is driven by a `$dff` cell, that ``y`` is connected to the output port ``Q``, that the ``clk`` signal goes into the ``CLK`` input port of the cell, and that the data comes from an auto-generated wire into the input ``D`` of the flip-flop cell (indicated by the ``$`` at the @@ -313,7 +313,7 @@ inputs. To add a pattern we add a colon followed by the pattern to the ``%ci`` action. The pattern itself starts with ``-`` or ``+``, indicating if it is an include or exclude pattern, followed by an optional comma separated list of cell types, followed by an optional comma separated list of port names in square -brackets. In this case, we want to exclude the ``S`` port of the ``$mux`` cell +brackets. In this case, we want to exclude the ``S`` port of the `$mux` cell type with :yoscrypt:`show y %ci5:-$mux[S]`: .. figure:: /_images/code_examples/selections/memdemo_03.* @@ -334,7 +334,7 @@ multiplexer select inputs and flip-flop cells: Output of ``show y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff`` Or we could use :yoscrypt:`show y %ci*:-[CLK,S]:+$dff:+$mux` instead, following -the input cone all the way but only following ``$dff`` and ``$mux`` cells, and +the input cone all the way but only following `$dff` and `$mux` cells, and ignoring any ports named ``CLK`` or ``S``: .. TODO:: pending discussion on whether rule ordering is a bug or a feature @@ -371,8 +371,8 @@ selection instead of overwriting it. select -del reg_42 # but not this one select -add state %ci # and add more stuff -Within a select expression the token ``%`` can be used to push the previous selection -on the stack. +Within a select expression the token ``%`` can be used to push the previous +selection on the stack. .. code:: yoscrypt @@ -387,16 +387,16 @@ Storing and recalling selections The current selection can be stored in memory with the command ``select -set ``. It can later be recalled using ``select @``. In fact, the ``@`` expression pushes the stored selection on the stack maintained by -the :cmd:ref:`select` command. So for example :yoscrypt:`select @foo @bar %i` -will select the intersection between the stored selections ``foo`` and ``bar``. +the `select` command. So for example :yoscrypt:`select @foo @bar %i` will select +the intersection between the stored selections ``foo`` and ``bar``. In larger investigation efforts it is highly recommended to maintain a script that sets up relevant selections, so they can easily be recalled, for example when Yosys needs to be re-run after a design or source code change. -The :cmd:ref:`history` command can be used to list all recent interactive -commands. This feature can be useful for creating such a script from the -commands used in an interactive session. +The `history` command can be used to list all recent interactive commands. This +feature can be useful for creating such a script from the commands used in an +interactive session. Remember that select expressions can also be used directly as arguments to most commands. Some commands also accept a single select argument to some options. In diff --git a/docs/source/using_yosys/synthesis/abc.rst b/docs/source/using_yosys/synthesis/abc.rst index fca9ddec0..ba12cabc1 100644 --- a/docs/source/using_yosys/synthesis/abc.rst +++ b/docs/source/using_yosys/synthesis/abc.rst @@ -10,20 +10,19 @@ fine-grained optimisation and LUT mapping. Yosys has two different commands, which both use this logic toolbox, but use it in different ways. -The :cmd:ref:`abc` pass can be used for both ASIC (e.g. :yoscrypt:`abc --liberty`) and FPGA (:yoscrypt:`abc -lut`) mapping, but this page will focus on -FPGA mapping. +The `abc` pass can be used for both ASIC (e.g. :yoscrypt:`abc -liberty`) and +FPGA (:yoscrypt:`abc -lut`) mapping, but this page will focus on FPGA mapping. -The :cmd:ref:`abc9` pass generally provides superior mapping quality due to -being aware of combination boxes and DFF and LUT timings, giving it a more -global view of the mapping problem. +The `abc9` pass generally provides superior mapping quality due to being aware +of combination boxes and DFF and LUT timings, giving it a more global view of +the mapping problem. .. _ABC: https://github.com/berkeley-abc/abc ABC: the unit delay model, simple and efficient ----------------------------------------------- -The :cmd:ref:`abc` pass uses a highly simplified view of an FPGA: +The `abc` pass uses a highly simplified view of an FPGA: - An FPGA is made up of a network of inputs that connect through LUTs to a network of outputs. These inputs may actually be I/O pins, D flip-flops, @@ -126,7 +125,7 @@ guide to the syntax: By convention, all delays in ``specify`` blocks are in integer picoseconds. Files containing ``specify`` blocks should be read with the ``-specify`` option -to :cmd:ref:`read_verilog` so that they aren't skipped. +to `read_verilog` so that they aren't skipped. LUTs ^^^^ @@ -145,9 +144,9 @@ DFFs DFFs should be annotated with an ``(* abc9_flop *)`` attribute, however ABC9 has some specific requirements for this to be valid: - the DFF must initialise to -zero (consider using :cmd:ref:`dfflegalize` to ensure this). - the DFF cannot -have any asynchronous resets/sets (see the simplification idiom and the Boxes -section for what to do here). +zero (consider using `dfflegalize` to ensure this). - the DFF cannot have any +asynchronous resets/sets (see the simplification idiom and the Boxes section for +what to do here). It is worth noting that in pure ``abc9`` mode, only the setup and arrival times are passed to ABC9 (specifically, they are modelled as buffers with the given @@ -158,9 +157,9 @@ Some vendors have universal DFF models which include async sets/resets even when they're unused. Therefore *the simplification idiom* exists to handle this: by using a ``techmap`` file to discover flops which have a constant driver to those asynchronous controls, they can be mapped into an intermediate, simplified flop -which qualifies as an ``(* abc9_flop *)``, ran through :cmd:ref:`abc9`, and then -mapped back to the original flop. This is used in :cmd:ref:`synth_intel_alm` and -:cmd:ref:`synth_quicklogic` for the PolarPro3. +which qualifies as an ``(* abc9_flop *)``, ran through `abc9`, and then mapped +back to the original flop. This is used in `synth_intel_alm` and +`synth_quicklogic` for the PolarPro3. DFFs are usually specified to have setup constraints against the clock on the input signals, and an arrival time for the ``Q`` output. @@ -177,5 +176,6 @@ implemented as whiteboxes too. Boxes are arguably the biggest advantage that ABC9 has over ABC: by being aware of carry chains and DSPs, it avoids optimising for a path that isn't the actual critical path, while the generally-longer paths result in ABC9 being able to -reduce design area by mapping other logic to larger-but-slower cells. +reduce design area by mapping other logic to slower cells with greater logic +density. diff --git a/docs/source/using_yosys/synthesis/cell_libs.rst b/docs/source/using_yosys/synthesis/cell_libs.rst index 4e800bdf2..50811fd1e 100644 --- a/docs/source/using_yosys/synthesis/cell_libs.rst +++ b/docs/source/using_yosys/synthesis/cell_libs.rst @@ -54,7 +54,7 @@ Our circuit now looks like this: :class: width-helper invert-helper :name: counter-hierarchy - ``counter`` after :cmd:ref:`hierarchy` + ``counter`` after `hierarchy` Coarse-grain representation ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -82,7 +82,7 @@ Logic gate mapping .. figure:: /_images/code_examples/intro/counter_02.* :class: width-helper invert-helper - ``counter`` after :cmd:ref:`techmap` + ``counter`` after `techmap` Mapping to hardware ~~~~~~~~~~~~~~~~~~~ @@ -98,11 +98,11 @@ our internal cell library will be mapped to: :name: mycells-lib :caption: :file:`mycells.lib` -Recall that the Yosys built-in logic gate types are ``$_NOT_``, ``$_AND_``, -``$_OR_``, ``$_XOR_``, and ``$_MUX_`` with an assortment of dff memory types. +Recall that the Yosys built-in logic gate types are `$_NOT_`, `$_AND_`, `$_OR_`, +`$_XOR_`, and `$_MUX_` with an assortment of dff memory types. :ref:`mycells-lib` defines our target cells as ``BUF``, ``NOT``, ``NAND``, ``NOR``, and ``DFF``. Mapping between these is performed with the commands -:cmd:ref:`dfflibmap` and :cmd:ref:`abc` as follows: +`dfflibmap` and `abc` as follows: .. literalinclude:: /code_examples/intro/counter.ys :language: yoscrypt @@ -117,8 +117,8 @@ The final version of our ``counter`` module looks like this: ``counter`` after hardware cell mapping -Before finally being output as a verilog file with :cmd:ref:`write_verilog`, -which can then be loaded into another tool: +Before finally being output as a verilog file with `write_verilog`, which can +then be loaded into another tool: .. literalinclude:: /code_examples/intro/counter.ys :language: yoscrypt diff --git a/docs/source/using_yosys/synthesis/extract.rst b/docs/source/using_yosys/synthesis/extract.rst index c9b76840e..73957bb55 100644 --- a/docs/source/using_yosys/synthesis/extract.rst +++ b/docs/source/using_yosys/synthesis/extract.rst @@ -1,13 +1,13 @@ The extract pass ---------------- -- Like the :cmd:ref:`techmap` pass, the :cmd:ref:`extract` pass is called with a - map file. It compares the circuits inside the modules of the map file with the - design and looks for sub-circuits in the design that match any of the modules - in the map file. -- If a match is found, the :cmd:ref:`extract` pass will replace the matching - subcircuit with an instance of the module from the map file. -- In a way the :cmd:ref:`extract` pass is the inverse of the techmap pass. +- Like the `techmap` pass, the `extract` pass is called with a map file. It + compares the circuits inside the modules of the map file with the design and + looks for sub-circuits in the design that match any of the modules in the map + file. +- If a match is found, the `extract` pass will replace the matching subcircuit + with an instance of the module from the map file. +- In a way the `extract` pass is the inverse of the techmap pass. .. todo:: add/expand supporting text, also mention custom pattern matching and pmgen @@ -25,7 +25,7 @@ Example code can be found in |code_examples/macc|_. .. figure:: /_images/code_examples/macc/macc_simple_test_00a.* :class: width-helper invert-helper - before :cmd:ref:`extract` + before `extract` .. literalinclude:: /code_examples/macc/macc_simple_test.ys :language: yoscrypt @@ -34,7 +34,7 @@ Example code can be found in |code_examples/macc|_. .. figure:: /_images/code_examples/macc/macc_simple_test_00b.* :class: width-helper invert-helper - after :cmd:ref:`extract` + after `extract` .. literalinclude:: /code_examples/macc/macc_simple_test.v :language: verilog @@ -68,26 +68,26 @@ The wrap-extract-unwrap method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Often a coarse-grain element has a constant bit-width, but can be used to -implement operations with a smaller bit-width. For example, a 18x25-bit multiplier -can also be used to implement 16x20-bit multiplication. +implement operations with a smaller bit-width. For example, a 18x25-bit +multiplier can also be used to implement 16x20-bit multiplication. A way of mapping such elements in coarse grain synthesis is the wrap-extract-unwrap method: wrap Identify candidate-cells in the circuit and wrap them in a cell with a - constant wider bit-width using :cmd:ref:`techmap`. The wrappers use the same - parameters as the original cell, so the information about the original width - of the ports is preserved. Then use the :cmd:ref:`connwrappers` command to - connect up the bit-extended in- and outputs of the wrapper cells. + constant wider bit-width using `techmap`. The wrappers use the same parameters + as the original cell, so the information about the original width of the ports + is preserved. Then use the `connwrappers` command to connect up the + bit-extended in- and outputs of the wrapper cells. extract Now all operations are encoded using the same bit-width as the coarse grain - element. The :cmd:ref:`extract` command can be used to replace circuits with - cells of the target architecture. + element. The `extract` command can be used to replace circuits with cells of + the target architecture. unwrap - The remaining wrapper cell can be unwrapped using :cmd:ref:`techmap`. + The remaining wrapper cell can be unwrapped using `techmap`. Example: DSP48_MACC ~~~~~~~~~~~~~~~~~~~ @@ -127,7 +127,7 @@ Extract: :file:`macc_xilinx_xmap.v` :caption: :file:`macc_xilinx_xmap.v` ... simply use the same wrapping commands on this module as on the design to -create a template for the :cmd:ref:`extract` command. +create a template for the `extract` command. Unwrapping multipliers: :file:`macc_xilinx_unwrap_map.v` diff --git a/docs/source/using_yosys/synthesis/fsm.rst b/docs/source/using_yosys/synthesis/fsm.rst index e1ed55133..6fad81d54 100644 --- a/docs/source/using_yosys/synthesis/fsm.rst +++ b/docs/source/using_yosys/synthesis/fsm.rst @@ -1,14 +1,14 @@ FSM handling ============ -The :cmd:ref:`fsm` command identifies, extracts, optimizes (re-encodes), and +The `fsm` command identifies, extracts, optimizes (re-encodes), and re-synthesizes finite state machines. It again is a macro that calls a series of other commands: .. literalinclude:: /code_examples/macro_commands/fsm.ys :language: yoscrypt :start-after: #end: - :caption: Passes called by :cmd:ref:`fsm` + :caption: Passes called by `fsm` See also :doc:`/cmd/fsm`. @@ -18,34 +18,33 @@ general reported technique :cite:p:`fsmextract`. FSM detection ~~~~~~~~~~~~~ -The :cmd:ref:`fsm_detect` pass identifies FSM state registers. It sets the -``\fsm_encoding = "auto"`` attribute on any (multi-bit) wire that matches the +The `fsm_detect` pass identifies FSM state registers. It sets the +``fsm_encoding = "auto"`` attribute on any (multi-bit) wire that matches the following description: -- Does not already have the ``\fsm_encoding`` attribute. +- Does not already have the ``fsm_encoding`` attribute. - Is not an output of the containing module. -- Is driven by single ``$dff`` or ``$adff`` cell. -- The ``\D``-Input of this ``$dff`` or ``$adff`` cell is driven by a - multiplexer tree that only has constants or the old state value on its - leaves. +- Is driven by single `$dff` or `$adff` cell. +- The ``D``-Input of this `$dff` or `$adff` cell is driven by a multiplexer + tree that only has constants or the old state value on its leaves. - The state value is only used in the said multiplexer tree or by simple - relational cells that compare the state value to a constant (usually ``$eq`` + relational cells that compare the state value to a constant (usually `$eq` cells). This heuristic has proven to work very well. It is possible to overwrite it by -setting ``\fsm_encoding = "auto"`` on registers that should be considered FSM -state registers and setting ``\fsm_encoding = "none"`` on registers that match +setting ``fsm_encoding = "auto"`` on registers that should be considered FSM +state registers and setting ``fsm_encoding = "none"`` on registers that match the above criteria but should not be considered FSM state registers. -Note however that marking state registers with ``\fsm_encoding`` that are not +Note however that marking state registers with ``fsm_encoding`` that are not suitable for FSM recoding can cause synthesis to fail or produce invalid results. FSM extraction ~~~~~~~~~~~~~~ -The :cmd:ref:`fsm_extract` pass operates on all state signals marked with the -(``\fsm_encoding != "none"``) attribute. For each state signal the following +The `fsm_extract` pass operates on all state signals marked with the +(``fsm_encoding != "none"``) attribute. For each state signal the following information is determined: - The state registers @@ -64,10 +63,10 @@ information is determined: The state registers (and asynchronous reset state, if applicable) is simply determined by identifying the driver for the state signal. -From there the ``$mux-tree`` driving the state register inputs is recursively -traversed. All select inputs are control signals and the leaves of the -``$mux-tree`` are the states. The algorithm fails if a non-constant leaf that is -not the state signal itself is found. +From there the `$mux`\ -tree driving the state register inputs is recursively +traversed. All select inputs are control signals and the leaves of the `$mux`\ +-tree are the states. The algorithm fails if a non-constant leaf that is not the +state signal itself is found. The list of control outputs is initialized with the bits from the state signal. It is then extended by adding all values that are calculated by cells that @@ -85,8 +84,8 @@ given set of result signals using a set of signal-value assignments. It can also be passed a list of stop-signals that abort the ConstEval algorithm if the value of a stop-signal is needed in order to calculate the result signals. -The :cmd:ref:`fsm_extract` pass uses the ConstEval class in the following way to -create a transition table. For each state: +The `fsm_extract` pass uses the ConstEval class in the following way to create a +transition table. For each state: 1. Create a ConstEval object for the module containing the FSM 2. Add all control inputs to the list of stop signals @@ -99,20 +98,19 @@ create a transition table. For each state: 6. If step 4 was successful: Emit transition -Finally a ``$fsm`` cell is created with the generated transition table and added +Finally a `$fsm` cell is created with the generated transition table and added to the module. This new cell is connected to the control signals and the old drivers for the control outputs are disconnected. FSM optimization ~~~~~~~~~~~~~~~~ -The :cmd:ref:`fsm_opt` pass performs basic optimizations on ``$fsm`` cells (not -including state recoding). The following optimizations are performed (in this -order): +The `fsm_opt` pass performs basic optimizations on `$fsm` cells (not including +state recoding). The following optimizations are performed (in this order): -- Unused control outputs are removed from the ``$fsm`` cell. The attribute - ``\unused_bits`` (that is usually set by the :cmd:ref:`opt_clean` pass) is - used to determine which control outputs are unused. +- Unused control outputs are removed from the `$fsm` cell. The attribute + ``unused_bits`` (that is usually set by the `opt_clean` pass) is used to + determine which control outputs are unused. - Control inputs that are connected to the same driver are merged. @@ -132,11 +130,10 @@ order): FSM recoding ~~~~~~~~~~~~ -The :cmd:ref:`fsm_recode` pass assigns new bit pattern to the states. Usually -this also implies a change in the width of the state signal. At the moment of -this writing only one-hot encoding with all-zero for the reset state is -supported. +The `fsm_recode` pass assigns new bit pattern to the states. Usually this also +implies a change in the width of the state signal. At the moment of this writing +only one-hot encoding with all-zero for the reset state is supported. -The :cmd:ref:`fsm_recode` pass can also write a text file with the changes -performed by it that can be used when verifying designs synthesized by Yosys -using Synopsys Formality. +The `fsm_recode` pass can also write a text file with the changes performed by +it that can be used when verifying designs synthesized by Yosys using Synopsys +Formality. diff --git a/docs/source/using_yosys/synthesis/index.rst b/docs/source/using_yosys/synthesis/index.rst index c00a940da..60581668f 100644 --- a/docs/source/using_yosys/synthesis/index.rst +++ b/docs/source/using_yosys/synthesis/index.rst @@ -8,17 +8,16 @@ coarse-grain optimizations before being mapped to hard blocks and fine-grain cells. Most commands in Yosys will target either coarse-grain representation or fine-grain representation, with only a select few compatible with both states. -Commands such as :cmd:ref:`proc`, :cmd:ref:`fsm`, and :cmd:ref:`memory` rely on -the additional information in the coarse-grain representation, along with a -number of optimizations such as :cmd:ref:`wreduce`, :cmd:ref:`share`, and -:cmd:ref:`alumacc`. :cmd:ref:`opt` provides optimizations which are useful in -both states, while :cmd:ref:`techmap` is used to convert coarse-grain cells -to the corresponding fine-grain representation. +Commands such as `proc`, `fsm`, and `memory` rely on the additional information +in the coarse-grain representation, along with a number of optimizations such as +`wreduce`, `share`, and `alumacc`. `opt` provides optimizations which are +useful in both states, while `techmap` is used to convert coarse-grain cells to +the corresponding fine-grain representation. Single-bit cells (logic gates, FFs) as well as LUTs, half-adders, and full-adders make up the bulk of the fine-grain representation and are necessary -for commands such as :cmd:ref:`abc`\ /:cmd:ref:`abc9`, :cmd:ref:`simplemap`, -:cmd:ref:`dfflegalize`, and :cmd:ref:`memory_map`. +for commands such as `abc`\ /`abc9`, `simplemap`, `dfflegalize`, and +`memory_map`. .. toctree:: :maxdepth: 3 diff --git a/docs/source/using_yosys/synthesis/memory.rst b/docs/source/using_yosys/synthesis/memory.rst index e95a64875..a8f2280f7 100644 --- a/docs/source/using_yosys/synthesis/memory.rst +++ b/docs/source/using_yosys/synthesis/memory.rst @@ -1,32 +1,32 @@ Memory handling =============== -The :cmd:ref:`memory` command +The `memory` command ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In the RTL netlist, memory reads and writes are individual cells. This makes -consolidating the number of ports for a memory easier. The :cmd:ref:`memory` -pass transforms memories to an implementation. Per default that is logic for -address decoders and registers. It also is a macro command that calls the other -common ``memory_*`` passes in a sensible order: +consolidating the number of ports for a memory easier. The `memory` pass +transforms memories to an implementation. Per default that is logic for address +decoders and registers. It also is a macro command that calls the other common +``memory_*`` passes in a sensible order: .. literalinclude:: /code_examples/macro_commands/memory.ys :language: yoscrypt :start-after: #end: - :caption: Passes called by :cmd:ref:`memory` + :caption: Passes called by `memory` .. todo:: Make ``memory_*`` notes less quick Some quick notes: -- :cmd:ref:`memory_dff` merges registers into the memory read- and write cells. -- :cmd:ref:`memory_collect` collects all read and write cells for a memory and +- `memory_dff` merges registers into the memory read- and write cells. +- `memory_collect` collects all read and write cells for a memory and transforms them into one multi-port memory cell. -- :cmd:ref:`memory_map` takes the multi-port memory cell and transforms it to - address decoder logic and registers. +- `memory_map` takes the multi-port memory cell and transforms it to address + decoder logic and registers. -For more information about :cmd:ref:`memory`, such as disabling certain sub -commands, see :doc:`/cmd/memory`. +For more information about `memory`, such as disabling certain sub commands, see +:doc:`/cmd/memory`. Example ------- @@ -75,22 +75,22 @@ For example: techmap -map my_memory_map.v memory_map -:cmd:ref:`memory_libmap` attempts to convert memory cells (``$mem_v2`` etc) into -hardware supported memory using a provided library (:file:`my_memory_map.txt` in the +`memory_libmap` attempts to convert memory cells (`$mem_v2` etc) into hardware +supported memory using a provided library (:file:`my_memory_map.txt` in the example above). Where necessary, emulation logic is added to ensure functional equivalence before and after this conversion. :yoscrypt:`techmap -map -my_memory_map.v` then uses :cmd:ref:`techmap` to map to hardware primitives. Any -leftover memory cells unable to be converted are then picked up by -:cmd:ref:`memory_map` and mapped to DFFs and address decoders. +my_memory_map.v` then uses `techmap` to map to hardware primitives. Any leftover +memory cells unable to be converted are then picked up by `memory_map` and +mapped to DFFs and address decoders. .. note:: More information about what mapping options are available and associated costs of each can be found by enabling debug outputs. This can be done with - the :cmd:ref:`debug` command, or by using the ``-g`` flag when calling Yosys - to globally enable debug messages. + the `debug` command, or by using the ``-g`` flag when calling Yosys to + globally enable debug messages. -For more on the lib format for :cmd:ref:`memory_libmap`, see +For more on the lib format for `memory_libmap`, see `passes/memory/memlib.md `_ @@ -110,13 +110,15 @@ Notes Memory kind selection ~~~~~~~~~~~~~~~~~~~~~ -The memory inference code will automatically pick target memory primitive based on memory geometry -and features used. Depending on the target, there can be up to four memory primitive classes -available for selection: +The memory inference code will automatically pick target memory primitive based +on memory geometry and features used. Depending on the target, there can be up +to four memory primitive classes available for selection: -- FF RAM (aka logic): no hardware primitive used, memory lowered to a bunch of FFs and multiplexers +- FF RAM (aka logic): no hardware primitive used, memory lowered to a bunch of + FFs and multiplexers - - Can handle arbitrary number of write ports, as long as all write ports are in the same clock domain + - Can handle arbitrary number of write ports, as long as all write ports are + in the same clock domain - Can handle arbitrary number and kind of read ports - LUT RAM (aka distributed RAM): uses LUT storage as RAM @@ -131,7 +133,8 @@ available for selection: - Supported on basically all FPGAs - Supports only synchronous reads - Two ports with separate clocks - - Usually supports true dual port (with notable exception of ice40 that only supports SDP) + - Usually supports true dual port (with notable exception of ice40 that only + supports SDP) - Usually supports asymmetric memories and per-byte write enables - Several kilobits in size @@ -155,38 +158,43 @@ available for selection: - Two ports, both with mutually exclusive synchronous read and write - Single clock - - Will not be automatically selected by memory inference code, needs explicit opt-in via - ram_style attribute + - Will not be automatically selected by memory inference code, needs explicit + opt-in via ram_style attribute -In general, you can expect the automatic selection process to work roughly like this: +In general, you can expect the automatic selection process to work roughly like +this: - If any read port is asynchronous, only LUT RAM (or FF RAM) can be used. -- If there is more than one write port, only block RAM can be used, and this needs to be a - hardware-supported true dual port pattern +- If there is more than one write port, only block RAM can be used, and this + needs to be a hardware-supported true dual port pattern - - … unless all write ports are in the same clock domain, in which case FF RAM can also be used, - but this is generally not what you want for anything but really small memories + - … unless all write ports are in the same clock domain, in which case FF RAM + can also be used, but this is generally not what you want for anything but + really small memories -- Otherwise, either FF RAM, LUT RAM, or block RAM will be used, depending on memory size +- Otherwise, either FF RAM, LUT RAM, or block RAM will be used, depending on + memory size This process can be overridden by attaching a ram_style attribute to the memory: -- `(* ram_style = "logic" *)` selects FF RAM -- `(* ram_style = "distributed" *)` selects LUT RAM -- `(* ram_style = "block" *)` selects block RAM -- `(* ram_style = "huge" *)` selects huge RAM +- ``(* ram_style = "logic" *)`` selects FF RAM +- ``(* ram_style = "distributed" *)`` selects LUT RAM +- ``(* ram_style = "block" *)`` selects block RAM +- ``(* ram_style = "huge" *)`` selects huge RAM It is an error if this override cannot be realized for the given target. -Many alternate spellings of the attribute are also accepted, for compatibility with other software. +Many alternate spellings of the attribute are also accepted, for compatibility +with other software. Initial data ~~~~~~~~~~~~ -Most FPGA targets support initializing all kinds of memory to user-provided values. If explicit -initialization is not used the initial memory value is undefined. Initial data can be provided by -either initial statements writing memory cells one by one of ``$readmemh`` or ``$readmemb`` system -tasks. For an example pattern, see `sr_init`_. +Most FPGA targets support initializing all kinds of memory to user-provided +values. If explicit initialization is not used the initial memory value is +undefined. Initial data can be provided by either initial statements writing +memory cells one by one of ``$readmemh`` or ``$readmemb`` system tasks. For an +example pattern, see `sr_init`_. .. _wbe: @@ -194,12 +202,13 @@ Write port with byte enables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Byte enables can be used with any supported pattern -- To ensure that multiple writes will be merged into one port, they need to have disjoint bit - ranges, have the same address, and the same clock -- Any write enable granularity will be accepted (down to per-bit write enables), but using smaller - granularity than natively supported by the target is very likely to be inefficient (eg. using - 4-bit bytes on ECP5 will result in either padding the bytes with 5 dummy bits to native 9-bit - units or splitting the RAM into two block RAMs) +- To ensure that multiple writes will be merged into one port, they need to have + disjoint bit ranges, have the same address, and the same clock +- Any write enable granularity will be accepted (down to per-bit write enables), + but using smaller granularity than natively supported by the target is very + likely to be inefficient (eg. using 4-bit bytes on ECP5 will result in either + padding the bytes with 5 dummy bits to native 9-bit units or splitting the RAM + into two block RAMs) .. code:: verilog @@ -240,7 +249,8 @@ Synchronous SDP with clock domain crossing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Will result in block RAM or LUT RAM depending on size -- No behavior guarantees in case of simultaneous read and write to the same address +- No behavior guarantees in case of simultaneous read and write to the same + address .. code:: verilog @@ -261,9 +271,9 @@ Synchronous SDP read first - The read and write parts can be in the same or different processes. - Will result in block RAM or LUT RAM depending on size -- As long as the same clock is used for both, yosys will ensure read-first behavior. This may - require extra circuitry on some targets for block RAM. If this is not necessary, use one of the - patterns below. +- As long as the same clock is used for both, yosys will ensure read-first + behavior. This may require extra circuitry on some targets for block RAM. If + this is not necessary, use one of the patterns below. .. code:: verilog @@ -281,8 +291,8 @@ Synchronous SDP read first Synchronous SDP with undefined collision behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Like above, but the read value is undefined when read and write ports target the same address in - the same cycle +- Like above, but the read value is undefined when read and write ports target + the same address in the same cycle .. code:: verilog @@ -322,8 +332,8 @@ Synchronous SDP with write-first behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Will result in block RAM or LUT RAM depending on size -- May use additional circuitry for block RAM if write-first is not natively supported. Will always - use additional circuitry for LUT RAM. +- May use additional circuitry for block RAM if write-first is not natively + supported. Will always use additional circuitry for LUT RAM. .. code:: verilog @@ -343,7 +353,8 @@ Synchronous SDP with write-first behavior Synchronous SDP with write-first behavior (alternate pattern) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- This pattern is supported for compatibility, but is much less flexible than the above +- This pattern is supported for compatibility, but is much less flexible than + the above .. code:: verilog @@ -378,8 +389,10 @@ Synchronous single-port RAM with mutually exclusive read/write ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Will result in single-port block RAM or LUT RAM depending on size -- This is the correct pattern to infer ice40 SPRAM (with manual ram_style selection) -- On targets that don't support read/write block RAM ports (eg. ice40), will result in SDP block RAM instead +- This is the correct pattern to infer ice40 SPRAM (with manual ram_style + selection) +- On targets that don't support read/write block RAM ports (eg. ice40), will + result in SDP block RAM instead - For block RAM, will use "NO_CHANGE" mode if available .. code:: verilog @@ -396,12 +409,14 @@ Synchronous single-port RAM with mutually exclusive read/write Synchronous single-port RAM with read-first behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Will only result in single-port block RAM when read-first behavior is natively supported; - otherwise, SDP RAM with additional circuitry will be used -- Many targets (Xilinx, ECP5, …) can only natively support read-first/write-first single-port RAM - (or TDP RAM) where the write_enable signal implies the read_enable signal (ie. can never write - without reading). The memory inference code will run a simple SAT solver on the control signals to - determine if this is the case, and insert emulation circuitry if it cannot be easily proven. +- Will only result in single-port block RAM when read-first behavior is natively + supported; otherwise, SDP RAM with additional circuitry will be used +- Many targets (Xilinx, ECP5, …) can only natively support + read-first/write-first single-port RAM (or TDP RAM) where the write_enable + signal implies the read_enable signal (ie. can never write without reading). + The memory inference code will run a simple SAT solver on the control signals + to determine if this is the case, and insert emulation circuitry if it cannot + be easily proven. .. code:: verilog @@ -418,7 +433,8 @@ Synchronous single-port RAM with write-first behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Will result in single-port block RAM or LUT RAM when supported -- Block RAMs will require extra circuitry if write-first behavior not natively supported +- Block RAMs will require extra circuitry if write-first behavior not natively + supported .. code:: verilog @@ -440,8 +456,8 @@ Synchronous read port with initial value ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Initial read port values can be combined with any other supported pattern -- If block RAM is used and initial read port values are not natively supported by the target, small - emulation circuit will be inserted +- If block RAM is used and initial read port values are not natively supported + by the target, small emulation circuit will be inserted .. code:: verilog @@ -459,10 +475,11 @@ Synchronous read port with initial value Read register reset patterns ---------------------------- -Resets can be combined with any other supported pattern (except that synchronous reset and -asynchronous reset cannot both be used on a single read port). If block RAM is used and the -selected reset (synchronous or asynchronous) is used but not natively supported by the target, small -emulation circuitry will be inserted. +Resets can be combined with any other supported pattern (except that synchronous +reset and asynchronous reset cannot both be used on a single read port). If +block RAM is used and the selected reset (synchronous or asynchronous) is used +but not natively supported by the target, small emulation circuitry will be +inserted. Synchronous reset, reset priority over enable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -520,22 +537,26 @@ Synchronous read port with asynchronous reset Asymmetric memory patterns -------------------------- -To construct an asymmetric memory (memory with read/write ports of differing widths): +To construct an asymmetric memory (memory with read/write ports of differing +widths): - Declare the memory with the width of the narrowest intended port - Split all wide ports into multiple narrow ports - To ensure the wide ports will be correctly merged: - - For the address, use a concatenation of actual address in the high bits and a constant in the - low bits - - Ensure the actual address is identical for all ports belonging to the wide port + - For the address, use a concatenation of actual address in the high bits and + a constant in the low bits + - Ensure the actual address is identical for all ports belonging to the wide + port - Ensure that clock is identical - - For read ports, ensure that enable/reset signals are identical (for write ports, the enable - signal may vary — this will result in using the byte enable functionality) + - For read ports, ensure that enable/reset signals are identical (for write + ports, the enable signal may vary — this will result in using the byte + enable functionality) -Asymmetric memory is supported on all targets, but may require emulation circuitry where not -natively supported. Note that when the memory is larger than the underlying block RAM primitive, -hardware asymmetric memory support is likely not to be used even if present as it is more expensive. +Asymmetric memory is supported on all targets, but may require emulation +circuitry where not natively supported. Note that when the memory is larger +than the underlying block RAM primitive, hardware asymmetric memory support is +likely not to be used even if present as it is more expensive. .. _wide_sr: @@ -615,20 +636,25 @@ Wide write port True dual port (TDP) patterns ----------------------------- -- Many different variations of true dual port memory can be created by combining two single-port RAM - patterns on the same memory -- When TDP memory is used, memory inference code has much less maneuver room to create requested - semantics compared to individual single-port patterns (which can end up lowered to SDP memory - where necessary) — supported patterns depend strongly on the target -- In particular, when both ports have the same clock, it's likely that "undefined collision" mode - needs to be manually selected to enable TDP memory inference -- The examples below are non-exhaustive — many more combinations of port types are possible -- Note: if two write ports are in the same process, this defines a priority relation between them - (if both ports are active in the same clock, the later one wins). On almost all targets, this will - result in a bit of extra circuitry to ensure the priority semantics. If this is not what you want, - put them in separate processes. +- Many different variations of true dual port memory can be created by combining + two single-port RAM patterns on the same memory +- When TDP memory is used, memory inference code has much less maneuver room to + create requested semantics compared to individual single-port patterns (which + can end up lowered to SDP memory where necessary) — supported patterns depend + strongly on the target +- In particular, when both ports have the same clock, it's likely that + "undefined collision" mode needs to be manually selected to enable TDP memory + inference +- The examples below are non-exhaustive — many more combinations of port types + are possible +- Note: if two write ports are in the same process, this defines a priority + relation between them (if both ports are active in the same clock, the later + one wins). On almost all targets, this will result in a bit of extra circuitry + to ensure the priority semantics. If this is not what you want, put them in + separate processes. - - Priority is not supported when using the verific front end and any priority semantics are ignored. + - Priority is not supported when using the verific front end and any priority + semantics are ignored. TDP with different clocks, exclusive read/write ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -654,7 +680,8 @@ TDP with different clocks, exclusive read/write TDP with same clock, read-first behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- This requires hardware inter-port read-first behavior, and will only work on some targets (Xilinx, Nexus) +- This requires hardware inter-port read-first behavior, and will only work on + some targets (Xilinx, Nexus) .. code:: verilog @@ -677,9 +704,10 @@ TDP with same clock, read-first behavior TDP with multiple read ports ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- The combination of a single write port with an arbitrary amount of read ports is supported on all - targets — if a multi-read port primitive is available (like Xilinx RAM64M), it'll be used as - appropriate. Otherwise, the memory will be automatically split into multiple primitives. +- The combination of a single write port with an arbitrary amount of read ports + is supported on all targets — if a multi-read port primitive is available + (like Xilinx RAM64M), it'll be used as appropriate. Otherwise, the memory + will be automatically split into multiple primitives. .. code:: verilog diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst index 2a06aadd1..43b558739 100644 --- a/docs/source/using_yosys/synthesis/opt.rst +++ b/docs/source/using_yosys/synthesis/opt.rst @@ -6,32 +6,32 @@ This chapter outlines these optimizations. .. todo:: "outlines these optimizations" or "outlines *some*.."? -The :cmd:ref:`opt` macro command +The `opt` macro command -------------------------------- -The Yosys pass :cmd:ref:`opt` runs a number of simple optimizations. This -includes removing unused signals and cells and const folding. It is recommended -to run this pass after each major step in the synthesis script. As listed in +The Yosys pass `opt` runs a number of simple optimizations. This includes +removing unused signals and cells and const folding. It is recommended to run +this pass after each major step in the synthesis script. As listed in :doc:`/cmd/opt`, this macro command calls the following ``opt_*`` commands: .. literalinclude:: /code_examples/macro_commands/opt.ys :language: yoscrypt :start-after: #end: - :caption: Passes called by :cmd:ref:`opt` + :caption: Passes called by `opt` .. _adv_opt_expr: -Constant folding and simple expression rewriting - :cmd:ref:`opt_expr` +Constant folding and simple expression rewriting - `opt_expr` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. todo:: unsure if this is too much detail and should be in :doc:`/yosys_internals/index` This pass performs constant folding on the internal combinational cell types -described in :doc:`/yosys_internals/formats/cell_library`. This means a cell -with all constant inputs is replaced with the constant value this cell drives. -In some cases this pass can also optimize cells with some constant inputs. +described in :doc:`/cell_index`. This means a cell with all +constant inputs is replaced with the constant value this cell drives. In some +cases this pass can also optimize cells with some constant inputs. -.. table:: Const folding rules for ``$_AND_`` cells as used in :cmd:ref:`opt_expr`. +.. table:: Const folding rules for `$_AND_` cells as used in `opt_expr`. :name: tab:opt_expr_and :align: center @@ -54,7 +54,7 @@ In some cases this pass can also optimize cells with some constant inputs. ========= ========= =========== :numref:`Table %s ` shows the replacement rules used for -optimizing an ``$_AND_`` gate. The first three rules implement the obvious const +optimizing an `$_AND_` gate. The first three rules implement the obvious const folding rules. Note that 'any' might include dynamic values calculated by other parts of the circuit. The following three lines propagate undef (X) states. These are the only three cases in which it is allowed to propagate an undef @@ -66,33 +66,33 @@ substitutions are possible they are performed first, in the hope that the 'any' will change to an undef value or a 1 and therefore the output can be set to undef. -The last two lines simply replace an ``$_AND_`` gate with one constant-1 input +The last two lines simply replace an `$_AND_` gate with one constant-1 input with a buffer. -Besides this basic const folding the :cmd:ref:`opt_expr` pass can replace 1-bit -wide ``$eq`` and ``$ne`` cells with buffers or not-gates if one input is -constant. Equality checks may also be reduced in size if there are redundant -bits in the arguments (i.e. bits which are constant on both inputs). This can, -for example, result in a 32-bit wide constant like ``255`` being reduced to the -8-bit value of ``8'11111111`` if the signal being compared is only 8-bit as in +Besides this basic const folding the `opt_expr` pass can replace 1-bit wide +`$eq` and `$ne` cells with buffers or not-gates if one input is constant. +Equality checks may also be reduced in size if there are redundant bits in the +arguments (i.e. bits which are constant on both inputs). This can, for example, +result in a 32-bit wide constant like ``255`` being reduced to the 8-bit value +of ``8'11111111`` if the signal being compared is only 8-bit as in :ref:`addr_gen_clean` of :doc:`/getting_started/example_synth`. -The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing ``$mux`` -cells, as these cells are often used to model decision-trees and breaking these -trees can interfere with other optimizations. +The `opt_expr` pass is very conservative regarding optimizing `$mux` cells, as +these cells are often used to model decision-trees and breaking these trees can +interfere with other optimizations. .. literalinclude:: /code_examples/opt/opt_expr.ys :language: Verilog :start-after: read_verilog <fixup_ports()`` after changing the ``port_*`` properties of wires. - You can safely remove cells or change the ``connections`` property of a cell, @@ -242,7 +237,7 @@ Use ``log_cmd_error()`` to report a recoverable error: .. code:: C++ - if (design->selection_stack.back().empty()) + if (design->selection().empty()) log_cmd_error("This command can't operator on an empty selection!\n"); Use ``log_assert()`` and ``log_abort()`` instead of ``assert()`` and ``abort()``. diff --git a/docs/source/yosys_internals/extending_yosys/functional_ir.rst b/docs/source/yosys_internals/extending_yosys/functional_ir.rst index a763e0508..4f363623e 100644 --- a/docs/source/yosys_internals/extending_yosys/functional_ir.rst +++ b/docs/source/yosys_internals/extending_yosys/functional_ir.rst @@ -1,94 +1,524 @@ Writing a new backend using FunctionalIR -=========================================== +======================================== -To simplify the writing of backends for functional languages or similar targets, Yosys provides an alternative intermediate representation called FunctionalIR which maps more directly on those targets. +What is FunctionalIR +-------------------- -FunctionalIR represents the design as a function ``(inputs, current_state) -> (outputs, next_state)``. -This function is broken down into a series of assignments to variables. -Each assignment is a simple operation, such as an addition. -Complex operations are broken up into multiple steps. -For example, an RTLIL addition will be translated into a sign/zero extension of the inputs, followed by an addition. +To simplify the writing of backends for functional languages or similar targets, +Yosys provides an alternative intermediate representation called FunctionalIR +which maps more directly on those targets. -Like SSA form, each variable is assigned to exactly once. -We can thus treat variables and assignments as equivalent and, since this is a graph-like representation, those variables are also called "nodes". -Unlike RTLIL's cells and wires representation, this representation is strictly ordered (topologically sorted) with definitions preceding their use. +FunctionalIR represents the design as a function ``(inputs, current_state) -> +(outputs, next_state)``. This function is broken down into a series of +assignments to variables. Each assignment is a simple operation, such as an +addition. Complex operations are broken up into multiple steps. For example, an +RTLIL addition will be translated into a sign/zero extension of the inputs, +followed by an addition. -Every node has a "sort" (the FunctionalIR term for what might otherwise be called a "type"). The sorts available are +Like SSA form, each variable is assigned to exactly once. We can thus treat +variables and assignments as equivalent and, since this is a graph-like +representation, those variables are also called "nodes". Unlike RTLIL's cells +and wires representation, this representation is strictly ordered (topologically +sorted) with definitions preceding their use. + +Every node has a "sort" (the FunctionalIR term for what might otherwise be +called a "type"). The sorts available are - ``bit[n]`` for an ``n``-bit bitvector, and - ``memory[n,m]`` for an immutable array of ``2**n`` values of sort ``bit[m]``. -In terms of actual code, Yosys provides a class ``Functional::IR`` that represents a design in FunctionalIR. -``Functional::IR::from_module`` generates an instance from an RTLIL module. -The entire design is stored as a whole in an internal data structure. -To access the design, the ``Functional::Node`` class provides a reference to a particular node in the design. -The ``Functional::IR`` class supports the syntax ``for(auto node : ir)`` to iterate over every node. +In terms of actual code, Yosys provides a class ``Functional::IR`` that +represents a design in FunctionalIR. ``Functional::IR::from_module`` generates +an instance from an RTLIL module. The entire design is stored as a whole in an +internal data structure. To access the design, the ``Functional::Node`` class +provides a reference to a particular node in the design. The ``Functional::IR`` +class supports the syntax ``for(auto node : ir)`` to iterate over every node. -``Functional::IR`` also keeps track of inputs, outputs and states. -By a "state" we mean a pair of a "current state" input and a "next state" output. -One such pair is created for every register and for every memory. -Every input, output and state has a name (equal to their name in RTLIL), a sort and a kind. -The kind field usually remains as the default value ``$input``, ``$output`` or ``$state``, however some RTLIL cells such as ``$assert`` or ``$anyseq`` generate auxiliary inputs/outputs/states that are given a different kind to distinguish them from ordinary RTLIL inputs/outputs/states. +``Functional::IR`` also keeps track of inputs, outputs and states. By a "state" +we mean a pair of a "current state" input and a "next state" output. One such +pair is created for every register and for every memory. Every input, output and +state has a name (equal to their name in RTLIL), a sort and a kind. The kind +field usually remains as the default value ``$input``, ``$output`` or +``$state``, however some RTLIL cells such as ``$assert`` or ``$anyseq`` generate +auxiliary inputs/outputs/states that are given a different kind to distinguish +them from ordinary RTLIL inputs/outputs/states. -- To access an individual input/output/state, use ``ir.input(name, kind)``, ``ir.output(name, kind)`` or ``ir.state(name, kind)``. ``kind`` defaults to the default kind. -- To iterate over all inputs/outputs/states of a certain kind, methods ``ir.inputs``, ``ir.outputs``, ``ir.states`` are provided. Their argument defaults to the default kinds mentioned. -- To iterate over inputs/outputs/states of any kind, use ``ir.all_inputs``, ``ir.all_outputs`` and ``ir.all_states``. -- Outputs have a node that indicate the value of the output, this can be retrieved via ``output.value()``. -- States have a node that indicate the next value of the state, this can be retrieved via ``state.next_value()``. - They also have an initial value that is accessed as either ``state.initial_value_signal()`` or ``state.initial_value_memory()``, depending on their sort. +- To access an individual input/output/state, use ``ir.input(name, kind)``, + ``ir.output(name, kind)`` or ``ir.state(name, kind)``. ``kind`` defaults to + the default kind. +- To iterate over all inputs/outputs/states of a certain kind, methods + ``ir.inputs``, ``ir.outputs``, ``ir.states`` are provided. Their argument + defaults to the default kinds mentioned. +- To iterate over inputs/outputs/states of any kind, use ``ir.all_inputs``, + ``ir.all_outputs`` and ``ir.all_states``. +- Outputs have a node that indicate the value of the output, this can be + retrieved via ``output.value()``. +- States have a node that indicate the next value of the state, this can be + retrieved via ``state.next_value()``. They also have an initial value that is + accessed as either ``state.initial_value_signal()`` or + ``state.initial_value_memory()``, depending on their sort. -Each node has a "function", which defines its operation (for a complete list of functions and a specification of their operation, see ``functional.h``). -Functions are represented as an enum ``Functional::Fn`` and the function field can be accessed as ``node.fn()``. -Since the most common operation is a switch over the function that also accesses the arguments, the ``Node`` class provides a method ``visit`` that implements the visitor pattern. -For example, for an addition node ``node`` with arguments ``n1`` and ``n2``, ``node.visit(visitor)`` would call ``visitor.add(node, n1, n2)``. -Thus typically one would implement a class with a method for every function. -Visitors should inherit from either ``Functional::AbstractVisitor`` or ``Functional::DefaultVisitor``. -The former will produce a compiler error if a case is unhandled, the latter will call ``default_handler(node)`` instead. -Visitor methods should be marked as ``override`` to provide compiler errors if the arguments are wrong. +Each node has a "function", which defines its operation (for a complete list of +functions and a specification of their operation, see ``functional.h``). +Functions are represented as an enum ``Functional::Fn`` and the function field +can be accessed as ``node.fn()``. Since the most common operation is a switch +over the function that also accesses the arguments, the ``Node`` class provides +a method ``visit`` that implements the visitor pattern. For example, for an +addition node ``node`` with arguments ``n1`` and ``n2``, ``node.visit(visitor)`` +would call ``visitor.add(node, n1, n2)``. Thus typically one would implement a +class with a method for every function. Visitors should inherit from either +``Functional::AbstractVisitor`` or +``Functional::DefaultVisitor``. The former will produce a compiler +error if a case is unhandled, the latter will call ``default_handler(node)`` +instead. Visitor methods should be marked as ``override`` to provide compiler +errors if the arguments are wrong. Utility classes ------------------ +~~~~~~~~~~~~~~~ -``functional.h`` also provides utility classes that are independent of the main FunctionalIR representation but are likely to be useful for backends. +``functional.h`` also provides utility classes that are independent of the main +FunctionalIR representation but are likely to be useful for backends. -``Functional::Writer`` provides a simple formatting class that wraps a ``std::ostream`` and provides the following methods: +``Functional::Writer`` provides a simple formatting class that wraps a +``std::ostream`` and provides the following methods: - ``writer << value`` wraps ``os << value``. -- ``writer.print(fmt, value0, value1, value2, ...)`` replaces ``{0}``, ``{1}``, ``{2}``, etc in the string ``fmt`` with ``value0``, ``value1``, ``value2``, resp. - Each value is formatted using ``os << value``. - It is also possible to write ``{}`` to refer to one past the last index, i.e. ``{1} {} {} {7} {}`` is equivalent to ``{1} {2} {3} {7} {8}``. -- ``writer.print_with(fn, fmt, value0, value1, value2, ...)`` functions much the same as ``print`` but it uses ``os << fn(value)`` to print each value and falls back to ``os << value`` if ``fn(value)`` is not legal. +- ``writer.print(fmt, value0, value1, value2, ...)`` replaces ``{0}``, ``{1}``, + ``{2}``, etc in the string ``fmt`` with ``value0``, ``value1``, ``value2``, + resp. Each value is formatted using ``os << value``. It is also possible to + write ``{}`` to refer to one past the last index, i.e. ``{1} {} {} {7} {}`` is + equivalent to ``{1} {2} {3} {7} {8}``. +- ``writer.print_with(fn, fmt, value0, value1, value2, ...)`` functions much the + same as ``print`` but it uses ``os << fn(value)`` to print each value and + falls back to ``os << value`` if ``fn(value)`` is not legal. -``Functional::Scope`` keeps track of variable names in a target language. -It is used to translate between different sets of legal characters and to avoid accidentally re-defining identifiers. -Users should derive a class from ``Scope`` and supply the following: +``Functional::Scope`` keeps track of variable names in a target language. It is +used to translate between different sets of legal characters and to avoid +accidentally re-defining identifiers. Users should derive a class from ``Scope`` +and supply the following: -- ``Scope`` takes a template argument that specifies a type that's used to uniquely distinguish variables. - Typically this would be ``int`` (if variables are used for ``Functional::IR`` nodes) or ``IdString``. -- The derived class should provide a constructor that calls ``reserve`` for every reserved word in the target language. -- A method ``bool is_legal_character(char c, int index)`` has to be provided that returns ``true`` iff ``c`` is legal in an identifier at position ``index``. +- ``Scope`` takes a template argument that specifies a type that's used to + uniquely distinguish variables. Typically this would be ``int`` (if variables + are used for ``Functional::IR`` nodes) or ``IdString``. +- The derived class should provide a constructor that calls ``reserve`` for + every reserved word in the target language. +- A method ``bool is_character_legal(char c, int index)`` has to be provided + that returns ``true`` iff ``c`` is legal in an identifier at position + ``index``. -Given an instance ``scope`` of the derived class, the following methods are then available: +Given an instance ``scope`` of the derived class, the following methods are then +available: - ``scope.reserve(std::string name)`` marks the given name as being in-use -- ``scope.unique_name(IdString suggestion)`` generates a previously unused name and attempts to make it similar to ``suggestion``. -- ``scope(Id id, IdString suggestion)`` functions similar to ``unique_name``, except that multiple calls with the same ``id`` are guaranteed to retrieve the same name (independent of ``suggestion``). +- ``scope.unique_name(IdString suggestion)`` generates a previously unused name + and attempts to make it similar to ``suggestion``. +- ``scope(Id id, IdString suggestion)`` functions similar to ``unique_name``, + except that multiple calls with the same ``id`` are guaranteed to retrieve the + same name (independent of ``suggestion``). ``sexpr.h`` provides classes that represent and pretty-print s-expressions. -S-expressions can be constructed with ``SExpr::list``, for example ``SExpr expr = SExpr::list("add", "x", SExpr::list("mul", "y", "z"))`` represents ``(add x (mul y z))`` -(by adding ``using SExprUtil::list`` to the top of the file, ``list`` can be used as shorthand for ``SExpr::list``). -For prettyprinting, ``SExprWriter`` wraps an ``std::ostream`` and provides the following methods: +S-expressions can be constructed with ``SExpr::list``, for example ``SExpr expr += SExpr::list("add", "x", SExpr::list("mul", "y", "z"))`` represents ``(add x +(mul y z))`` (by adding ``using SExprUtil::list`` to the top of the file, +``list`` can be used as shorthand for ``SExpr::list``). For prettyprinting, +``SExprWriter`` wraps an ``std::ostream`` and provides the following methods: -- ``writer << sexpr`` writes the provided expression to the output, breaking long lines and adding appropriate indentation. -- ``writer.open(sexpr)`` is similar to ``writer << sexpr`` but will omit the last closing parenthesis. - Further arguments can then be added separately with ``<<`` or ``open``. - This allows for printing large s-expressions without needing to construct the whole expression in memory first. -- ``writer.open(sexpr, false)`` is similar to ``writer.open(sexpr)`` but further arguments will not be indented. - This is used to avoid unlimited indentation on structures with unlimited nesting. +- ``writer << sexpr`` writes the provided expression to the output, breaking + long lines and adding appropriate indentation. +- ``writer.open(sexpr)`` is similar to ``writer << sexpr`` but will omit the + last closing parenthesis. Further arguments can then be added separately with + ``<<`` or ``open``. This allows for printing large s-expressions without + needing to construct the whole expression in memory first. +- ``writer.open(sexpr, false)`` is similar to ``writer.open(sexpr)`` but further + arguments will not be indented. This is used to avoid unlimited indentation on + structures with unlimited nesting. - ``writer.close(n = 1)`` closes the last ``n`` open s-expressions. -- ``writer.push()`` and ``writer.pop()`` are used to automatically close s-expressions. - ``writer.pop()`` closes all s-expressions opened since the last call to ``writer.push()``. +- ``writer.push()`` and ``writer.pop()`` are used to automatically close + s-expressions. ``writer.pop()`` closes all s-expressions opened since the last + call to ``writer.push()``. - ``writer.comment(string)`` writes a comment on a separate-line. - ``writer.comment(string, true)`` appends a comment to the last printed s-expression. -- ``writer.flush()`` flushes any buffering and should be called before any direct access to the underlying ``std::ostream``. It does not close unclosed parentheses. + ``writer.comment(string, true)`` appends a comment to the last printed + s-expression. +- ``writer.flush()`` flushes any buffering and should be called before any + direct access to the underlying ``std::ostream``. It does not close unclosed + parentheses. - The destructor calls ``flush`` but also closes all unclosed parentheses. + +.. _minimal backend: + +Example: A minimal functional backend +------------------------------------- + +At its most basic, there are three steps we need to accomplish for a minimal +functional backend. First, we need to convert our design into FunctionalIR. +This is most easily done by calling the ``Functional::IR::from_module()`` static +method with our top-level module, or iterating over and converting each of the +modules in our design. Second, we need to handle each of the +``Functional::Node``\ s in our design. Iterating over the ``Functional::IR`` +includes reading the module inputs and current state, but not writing the +results. So our final step is to handle the outputs and next state. + +In order to add an output command to Yosys, we implement the ``Yosys::Backend`` +class and provide an instance of it: + +.. literalinclude:: /code_examples/functional/dummy.cc + :language: c++ + :caption: Example source code for a minimal functional backend, ``dummy.cc`` + +Because we are using the ``Backend`` class, our ``"functional_dummy"`` is +registered as the ``write_functional_dummy`` command. The ``execute`` method is +the part that runs when the user calls the command, handling any options, +preparing the output file for writing, and iterating over selected modules in +the design. Since we don't have any options here, we set ``argidx = 1`` and +call the ``extra_args()`` method. This method will read the command arguments, +raising an error if there are any unexpected ones. It will also assign the +pointer ``f`` to the output file, or stdout if none is given. + +.. note:: + + For more on adding new commands to Yosys and how they work, refer to + :doc:`/yosys_internals/extending_yosys/extensions`. + +For this minimal example all we are doing is printing out each node. The +``node.name()`` method returns an ``RTLIL::IdString``, which we convert for +printing with ``id2cstr()``. Then, to print the function of the node, we use +``node.to_string()`` which gives us a string of the form ``function(args)``. The +``function`` part is the result of ``Functional::IR::fn_to_string(node.fn())``; +while ``args`` is the zero or more arguments passed to the function, most +commonly the name of another node. Behind the scenes, the ``node.to_string()`` +method actually wraps ``node.visit(visitor)`` with a private visitor whose +return type is ``std::string``. + +Finally we iterate over the module's outputs and states, using +``Functional::IROutput::value()`` and ``Functional::IRState::next_value()`` +respectively in order to get the results of the transfer function. + +Example: Adapting SMT-LIB backend for Rosette +--------------------------------------------- + +This section will introduce the SMT-LIB functional backend +(`write_functional_smt2`) and what changes are needed to work with another +s-expression target, `Rosette`_ (`write_functional_rosette`). + +.. _Rosette: http://emina.github.io/rosette/ + +Overview +~~~~~~~~ + + Rosette is a solver-aided programming language that extends `Racket`_ with + language constructs for program synthesis, verification, and more. To verify + or synthesize code, Rosette compiles it to logical constraints solved with + off-the-shelf `SMT`_ solvers. + + -- https://emina.github.io/rosette/ + +.. _Racket: http://racket-lang.org/ +.. _SMT: http://smtlib.cs.uiowa.edu/ + +Rosette, being backed by SMT solvers and written with s-expressions, uses code +very similar to the `write_functional_smt2` output. As a result, the SMT-LIB +functional backend can be used as a starting point for implementing a Rosette +backend. + +Full code listings for the initial SMT-LIB backend and the converted Rosette +backend are included in the Yosys source repository under +:file:`backends/functional` as ``smtlib.cc`` and ``smtlib_rosette.cc`` +respectively. Note that the Rosette language is an extension of the Racket +language; this guide tends to refer to Racket when talking about the underlying +semantics/syntax of the language. + +The major changes from the SMT-LIB backend are as follows: + +- all of the ``Smt`` prefixes in names are replaced with ``Smtr`` to mean + ``smtlib_rosette``; +- syntax is adjusted for Racket; +- data structures for input/output/state are changed from using + ``declare-datatype`` with statically typed fields, to using ``struct`` with no + static typing; +- the transfer function also loses its static typing; +- sign/zero extension in Rosette use the output width instead of the number of + extra bits, gaining static typing; +- the single scope is traded for a global scope with local scope for each + struct; +- initial state is provided as a constant value instead of a set of assertions; +- and the ``-provides`` option is introduced to more easily use generated code + within Rosette based applications. + +Scope +~~~~~ + +Our first addition to the `minimal backend`_ above is that for both SMT-LIB and +Rosette backends, we are now targetting real languages which bring with them +their own sets of constraints with what we can use as identifiers. This is +where the ``Functional::Scope`` class described above comes in; by using this +class we can safely rename our identifiers in the generated output without +worrying about collisions or illegal names/characters. + +In the SMT-LIB version, the ``SmtScope`` class implements ``Scope``; +provides a constructor that iterates over a list of reserved keywords, calling +``reserve`` on each; and defines the ``is_character_legal`` method to reject any +characters which are not allowed in SMT-LIB variable names to then be replaced +with underscores in the output. To use this scope we create an instance of it, +and call the ``Scope::unique_name()`` method to generate a unique and legal name +for each of our identifiers. + +In the Rosette version we update the list of legal ascii characters in the +``is_character_legal`` method to only those allowed in Racket variable names. + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: diff of ``Scope`` class + :start-at: -struct SmtScope : public Functional::Scope { + :end-at: }; + +For the reserved keywords we trade the SMT-LIB specification for Racket to +prevent parts of our design from accidentally being treated as Racket code. We +also no longer need to reserve ``pair``, ``first``, and ``second``. In +`write_functional_smt2` these are used for combining the ``(inputs, +current_state)`` and ``(outputs, next_state)`` into a single variable. Racket +provides this functionality natively with ``cons``, which we will see later. + +.. inlined diff for skipping the actual lists +.. code-block:: diff + :caption: diff of ``reserved_keywords`` list + + const char *reserved_keywords[] = { + - // reserved keywords from the smtlib spec + - ... + + // reserved keywords from the racket spec + + ... + + // reserved for our own purposes + - "pair", "Pair", "first", "second", + - "inputs", "state", + + "inputs", "state", "name", + nullptr + }; + +.. note:: We skip over the actual list of reserved keywords from both the smtlib + and racket specifications to save on space in this document. + +Sort +~~~~ + +Next up in `write_functional_smt2` we see the ``Sort`` class. This is a wrapper +for the ``Functional::Sort`` class, providing the additional functionality of +mapping variable declarations to s-expressions with the ``to_sexpr()`` method. +The main change from ``SmtSort`` to ``SmtrSort`` is a syntactical one with +signals represented as ``bitvector``\ s, and memories as ``list``\ s of signals. + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: diff of ``Sort`` wrapper + :start-at: SExpr to_sexpr() const { + :end-before: }; + +Struct +~~~~~~ + +As we saw in the `minimal backend`_ above, the ``Functional::IR`` class tracks +the set of inputs, the set of outputs, and the set of "state" variables. The +SMT-LIB backend maps each of these sets into its own ``SmtStruct``, with each +variable getting a corresponding field in the struct and a specified `Sort`_. +`write_functional_smt2` then defines each of these structs as a new +``datatype``, with each element being strongly-typed. + +In Rosette, rather than defining new datatypes for our structs, we use the +native ``struct``. We also only declare each field by name because Racket +provides less static typing. For ease of use, we provide the expected type for +each field as comments. + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: diff of ``write_definition`` method + :start-at: void write_definition + :end-before: template void write_value + +Each field is added to the ``SmtStruct`` with the ``insert`` method, which also +reserves a unique name (or accessor) within the `Scope`_. These accessors +combine the struct name and field name and are globally unique, being used in +the ``access`` method for reading values from the input/current state. + +.. literalinclude:: /generated/functional/smtlib.cc + :language: c++ + :caption: ``Struct::access()`` method + :start-at: SExpr access( + :end-before: }; + +In Rosette, struct fields are accessed as ``-`` so +including the struct name in the field name would be redundant. For +`write_functional_rosette` we instead choose to make field names unique only +within the struct, while accessors are unique across the whole module. We thus +modify the class constructor and ``insert`` method to support this; providing +one scope that is local to the struct (``local_scope``) and one which is shared +across the whole module (``global_scope``), leaving the ``access`` method +unchanged. + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: diff of struct constructor + :start-at: SmtStruct(std::string name, SmtScope &scope) + :end-before: void write_definition + +Finally, ``SmtStruct`` also provides a ``write_value`` template method which +calls a provided function on each element in the struct. This is used later for +assigning values to the output/next state pair. The only change here is to +remove the check for zero-argument constructors since this is not necessary with +Rosette ``struct``\ s. + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: diff of ``write_value`` method + :start-at: template void write_value + :end-before: SExpr access + +PrintVisitor +~~~~~~~~~~~~ + +Remember in the `minimal backend`_ we converted nodes into strings for writing +using the ``node.to_string()`` method, which wrapped ``node.visit()`` with a +private visitor. We now want a custom visitor which can convert nodes into +s-expressions. This is where the ``PrintVisitor`` comes in, implementing the +abstract ``Functional::AbstractVisitor`` class with a return type of ``SExpr``. +For most functions, the Rosette output is very similar to the corresponding +SMT-LIB function with minor adjustments for syntax. + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: portion of ``Functional::AbstractVisitor`` implementation diff showing similarities + :start-at: SExpr logical_shift_left + :end-at: "list-set-bv" + +However there are some differences in the two formats with regards to how +booleans are handled, with Rosette providing built-in functions for conversion. + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: portion of ``Functional::AbstractVisitor`` implementation diff showing differences + :start-at: SExpr from_bool + :end-before: SExpr extract + +Of note here is the rare instance of the Rosette implementation *gaining* static +typing rather than losing it. Where SMT_LIB calls zero/sign extension with the +number of extra bits needed (given by ``out_width - a.width()``), Rosette +instead specifies the type of the output (given by ``list("bitvector", +out_width)``). + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: zero/sign extension implementation diff + :start-after: SExpr buf( + :end-before: SExpr concat( + :lines: 2-3, 5-6 + +.. note:: Be sure to check the source code for the full list of differences here. + +Module +~~~~~~ + +With most of the supporting classes out of the way, we now reach our three main +steps from the `minimal backend`_. These are all handled by the ``SmtModule`` +class, with the mapping from RTLIL module to FunctionalIR happening in the +constructor. Each of the three ``SmtStruct``\ s; inputs, outputs, and state; +are also created in the constructor, with each value in the corresponding lists +in the IR being ``insert``\ ed. + +.. literalinclude:: /generated/functional/smtlib.cc + :language: c++ + :caption: ``SmtModule`` constructor + :start-at: SmtModule(Module + :end-at: } + +Since Racket uses the ``-`` to access struct fields, the ``SmtrModule`` instead +uses an underscore for the name of the initial state. + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: diff of ``Module`` constructor + :start-at: scope.reserve(name + :end-before: for (auto input + +The ``write`` method is then responsible for writing the FunctionalIR to the +output file, formatted for the corresponding backend. ``SmtModule::write()`` +breaks the output file down into four parts: defining the three structs, +declaring the ``pair`` datatype, defining the transfer function ``(inputs, +current_state) -> (outputs, next_state)`` with ``write_eval``, and declaring the +initial state with ``write_initial``. The only change for the ``SmtrModule`` is +that the ``pair`` declaration isn't needed. + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: diff of ``Module::write()`` method + :start-at: void write(std::ostream &out) + :end-at: } + +The ``write_eval`` method is where the FunctionalIR nodes, outputs, and next +state are handled. Just as with the `minimal backend`_, we iterate over the +nodes with ``for(auto n : ir)``, and then use the ``Struct::write_value()`` +method for the ``output_struct`` and ``state_struct`` to iterate over the +outputs and next state respectively. + +.. literalinclude:: /generated/functional/smtlib.cc + :language: c++ + :caption: iterating over FunctionalIR nodes in ``SmtModule::write_eval()`` + :start-at: for(auto n : ir) + :end-at: } + +The main differences between our two backends here are syntactical. First we +change the ``define-fun`` for the Racket style ``define`` which drops the +explicitly typed inputs/outputs. And then we change the final result from a +``pair`` to the native ``cons`` which acts in much the same way, returning both +the ``outputs`` and the ``next_state`` in a single variable. + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: diff of ``Module::write_eval()`` transfer function declaration + :start-at: w.open(list("define-fun" + :end-at: w.open(list("define" + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: diff of output/next state handling ``Module::write_eval()`` + :start-at: w.open(list("pair" + :end-at: w.pop(); + +For the ``write_initial`` method, the SMT-LIB backend uses ``declare-const`` and +``assert``\ s which must always hold true. For Rosette we instead define the +initial state as any other variable that can be used by external code. This +variable, ``[name]_initial``, can then be used in the ``[name]`` function call; +allowing the Rosette code to be used in the generation of the ``next_state``, +whereas the SMT-LIB code can only verify that a given ``next_state`` is correct. + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: diff of ``Module::write_initial()`` method + :start-at: void write_initial + :end-before: void write + +Backend +~~~~~~~ + +The final part is the ``Backend`` itself, with much of the same boiler plate as +the `minimal backend`_. The main difference is that we use the `Module`_ to +perform the actual processing. + +.. literalinclude:: /generated/functional/smtlib.cc + :language: c++ + :caption: The ``FunctionalSmtBackend`` + :start-at: struct FunctionalSmtBackend + :end-at: } FunctionalSmtBackend; + +There are two additions here for Rosette. The first is that the output file +needs to start with the ``#lang`` definition which tells the +compiler/interpreter that we want to use the Rosette language module. The +second is that the `write_functional_rosette` command takes an optional +argument, ``-provides``. If this argument is given, then the output file gets +an additional line declaring that everything in the file should be exported for +use; allowing the file to be treated as a Racket package with structs and +mapping function available for use externally. + +.. literalinclude:: /generated/functional/rosette.diff + :language: diff + :caption: relevant portion of diff of ``Backend::execute()`` method + :start-at: lang rosette/safe + :end-before: for (auto module diff --git a/docs/source/yosys_internals/extending_yosys/index.rst b/docs/source/yosys_internals/extending_yosys/index.rst index 2a4d2dfef..4ee21517b 100644 --- a/docs/source/yosys_internals/extending_yosys/index.rst +++ b/docs/source/yosys_internals/extending_yosys/index.rst @@ -10,5 +10,7 @@ of interest for developers looking to customise Yosys builds. extensions build_verific + functional_ir + contributing test_suites diff --git a/docs/source/yosys_internals/extending_yosys/test_suites.rst b/docs/source/yosys_internals/extending_yosys/test_suites.rst index 7a6b74977..3e5f45b94 100644 --- a/docs/source/yosys_internals/extending_yosys/test_suites.rst +++ b/docs/source/yosys_internals/extending_yosys/test_suites.rst @@ -1,25 +1,91 @@ Testing Yosys ============= -.. todo:: more about the included test suite +.. TODO:: more about the included test suite and how to add tests Automatic testing ----------------- -.. only:: html - - The `Yosys Git repo`_ has automatic testing of builds and running of the - included test suite on the following platforms: - - - Ubuntu |test-linux| - - macOS |test-macos| +The `Yosys Git repo`_ has automatic testing of builds and running of the +included test suite on both Ubuntu and macOS, as well as across range of +compiler versions. For up to date information, including OS versions, refer to +`the git actions page`_. .. _Yosys Git repo: https://github.com/YosysHQ/yosys - -.. |test-linux| image:: https://github.com/YosysHQ/yosys/actions/workflows/test-linux.yml/badge.svg?branch=main -.. |test-macos| image:: https://github.com/YosysHQ/yosys/actions/workflows/test-macos.yml/badge.svg?branch=main - -For up to date information, including OS versions, refer to `the git actions -page`_. - .. _the git actions page: https://github.com/YosysHQ/yosys/actions + +.. todo:: are unit tests currently working + +.. + How to add a unit test + ---------------------- + + Unit test brings some advantages, briefly, we can list some of them (reference + [1](https://en.wikipedia.org/wiki/Unit_testing)): + + * Tests reduce bugs in new features; + * Tests reduce bugs in existing features; + * Tests are good documentation; + * Tests reduce the cost of change; + * Tests allow refactoring; + + With those advantages in mind, it was required to choose a framework which fits + well with C/C++ code. Hence, `google test`_ was chosen, because it is widely + used and it is relatively easy learn. + + .. _google test: https://github.com/google/googletest + + Install and configure google test (manually) + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + In this section, you will see a brief description of how to install google test. + However, it is strongly recommended that you take a look to the official + repository (https://github.com/google/googletest) and refers to that if you have + any problem to install it. Follow the steps below: + + * Install: cmake and pthread + * Clone google test project from: https://github.com/google/googletest and enter + in the project directory + * Inside project directory, type: + + .. code-block:: console + + cmake -DBUILD_SHARED_LIBS=ON . + make + + * After compilation, copy all ``*.so`` inside directory ``googlemock`` and + ``googlemock/gtest`` to ``/usr/lib/`` + * Done! Now you can compile your tests. + + If you have any problem, go to the official repository to find help. + + Ps.: Some distros already have googletest packed. If your distro supports it, + you can use it instead of compile. + + Create a new unit test + ~~~~~~~~~~~~~~~~~~~~~~ + + If you want to add new unit tests for Yosys, just follow the steps below: + + * Go to directory :file:`test/unit/` + * In this directory you can find something similar Yosys's directory structure. + To create your unit test file you have to follow this pattern: + fileNameToImplementUnitTest + Test.cc. E.g.: if you want to implement the unit + test for ``kernel/celledges.cc``, you will need to create a file like this: + ``tests/unit/kernel/celledgesTest.cc``; + * Implement your unit test + + Run unit tests + ~~~~~~~~~~~~~~ + + To compile and run all unit tests, just go to yosys root directory and type: + + .. code-block:: console + + make unit-test + + If you want to remove all unit test files, type: + + .. code-block:: console + + make clean-unit-test diff --git a/docs/source/yosys_internals/flow/overview.rst b/docs/source/yosys_internals/flow/overview.rst index b357e5b50..3effe462b 100644 --- a/docs/source/yosys_internals/flow/overview.rst +++ b/docs/source/yosys_internals/flow/overview.rst @@ -20,7 +20,7 @@ given in :doc:`/yosys_internals/formats/rtlil_rep`. There is also a text representation of the RTLIL data structure that can be parsed using the RTLIL Frontend which is described in -:doc:`/yosys_internals/formats/rtlil_text`. +:doc:`/appendix/rtlil_text`. The design data may then be transformed using a series of passes that all operate on the RTLIL representation of the design. diff --git a/docs/source/yosys_internals/flow/verilog_frontend.rst b/docs/source/yosys_internals/flow/verilog_frontend.rst index f2eaeae97..b6a7ba8a0 100644 --- a/docs/source/yosys_internals/flow/verilog_frontend.rst +++ b/docs/source/yosys_internals/flow/verilog_frontend.rst @@ -599,16 +599,16 @@ The proc pass The ProcessGenerator converts a behavioural model in AST representation to a behavioural model in ``RTLIL::Process`` representation. The actual conversion -from a behavioural model to an RTL representation is performed by the -:cmd:ref:`proc` pass and the passes it launches: +from a behavioural model to an RTL representation is performed by the `proc` +pass and the passes it launches: -- | :cmd:ref:`proc_clean` and :cmd:ref:`proc_rmdead` +- | `proc_clean` and `proc_rmdead` | These two passes just clean up the ``RTLIL::Process`` structure. The - :cmd:ref:`proc_clean` pass removes empty parts (eg. empty assignments) from - the process and :cmd:ref:`proc_rmdead` detects and removes unreachable - branches from the process's decision trees. + `proc_clean` pass removes empty parts (eg. empty assignments) from the + process and `proc_rmdead` detects and removes unreachable branches from the + process's decision trees. -- | :cmd:ref:`proc_arst` +- | `proc_arst` | This pass detects processes that describe d-type flip-flops with asynchronous resets and rewrites the process to better reflect what they are modelling: Before this pass, an asynchronous reset has two @@ -616,22 +616,22 @@ from a behavioural model to an RTL representation is performed by the reset path. After this pass the sync rule for the reset is level-sensitive and the top-level ``RTLIL::SwitchRule`` has been removed. -- | :cmd:ref:`proc_mux` - | This pass converts the ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule``-tree to a - tree of multiplexers per written signal. After this, the ``RTLIL::Process`` - structure only contains the ``RTLIL::SyncRule`` s that describe the output - registers. +- | `proc_mux` + | This pass converts the ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule``-tree to + a tree of multiplexers per written signal. After this, the + ``RTLIL::Process`` structure only contains the ``RTLIL::SyncRule`` s that + describe the output registers. -- | :cmd:ref:`proc_dff` +- | `proc_dff` | This pass replaces the ``RTLIL::SyncRule``\ s to d-type flip-flops (with asynchronous resets if necessary). -- | :cmd:ref:`proc_dff` - | This pass replaces the ``RTLIL::MemWriteAction``\ s with ``$memwr`` cells. +- | `proc_memwr` + | This pass replaces the ``RTLIL::MemWriteAction``\ s with `$memwr` cells. -- | :cmd:ref:`proc_clean` - | A final call to :cmd:ref:`proc_clean` removes the now empty - ``RTLIL::Process`` objects. +- | `proc_clean` + | A final call to `proc_clean` removes the now empty ``RTLIL::Process`` + objects. Performing these last processing steps in passes instead of in the Verilog frontend has two important benefits: @@ -646,8 +646,8 @@ to extend the actual Verilog frontend. .. todo:: Synthesizing Verilog arrays - Add some information on the generation of ``$memrd`` and ``$memwr`` cells and - how they are processed in the memory pass. + Add some information on the generation of `$memrd` and `$memwr` cells and how + they are processed in the memory pass. .. todo:: Synthesizing parametric designs diff --git a/docs/source/yosys_internals/formats/cell_library.rst b/docs/source/yosys_internals/formats/cell_library.rst deleted file mode 100644 index 2e30ee25c..000000000 --- a/docs/source/yosys_internals/formats/cell_library.rst +++ /dev/null @@ -1,1241 +0,0 @@ -.. role:: verilog(code) - :language: Verilog - -.. _chapter:celllib: - -Internal cell library -===================== - -.. todo:: less academic, also check formatting consistency - -Most of the passes in Yosys operate on netlists, i.e. they only care about the -``RTLIL::Wire`` and ``RTLIL::Cell`` objects in an ``RTLIL::Module``. This -chapter discusses the cell types used by Yosys to represent a behavioural design -internally. - -.. TODO:: is this chapter split preserved - -This chapter is split in two parts. In the first part the internal RTL cells are -covered. These cells are used to represent the design on a coarse grain level. -Like in the original HDL code on this level the cells operate on vectors of -signals and complex cells like adders exist. In the second part the internal -gate cells are covered. These cells are used to represent the design on a -fine-grain gate-level. All cells from this category operate on single bit -signals. - -RTL cells ---------- - -Most of the RTL cells closely resemble the operators available in HDLs such as -Verilog or VHDL. Therefore Verilog operators are used in the following sections -to define the behaviour of the RTL cells. - -Note that all RTL cells have parameters indicating the size of inputs and -outputs. When passes modify RTL cells they must always keep the values of these -parameters in sync with the size of the signals connected to the inputs and -outputs. - -Simulation models for the RTL cells can be found in the file -:file:`techlibs/common/simlib.v` in the Yosys source tree. - -Unary operators -~~~~~~~~~~~~~~~ - -All unary RTL cells have one input port ``\A`` and one output port ``\Y``. They -also have the following parameters: - -``\A_SIGNED`` - Set to a non-zero value if the input ``\A`` is signed and therefore should be - sign-extended when needed. - -``\A_WIDTH`` - The width of the input port ``\A``. - -``\Y_WIDTH`` - The width of the output port ``\Y``. - -:numref:`tab:CellLib_unary` lists all cells for unary RTL operators. - -.. table:: Cell types for unary operators with their corresponding Verilog expressions. - :name: tab:CellLib_unary - - ================== ============ - Verilog Cell Type - ================== ============ - :verilog:`Y = ~A` $not - :verilog:`Y = +A` $pos - :verilog:`Y = -A` $neg - :verilog:`Y = &A` $reduce_and - :verilog:`Y = |A` $reduce_or - :verilog:`Y = ^A` $reduce_xor - :verilog:`Y = ~^A` $reduce_xnor - :verilog:`Y = |A` $reduce_bool - :verilog:`Y = !A` $logic_not - ================== ============ - -For the unary cells that output a logical value (``$reduce_and``, -``$reduce_or``, ``$reduce_xor``, ``$reduce_xnor``, ``$reduce_bool``, -``$logic_not``), when the ``\Y_WIDTH`` parameter is greater than 1, the output -is zero-extended, and only the least significant bit varies. - -Note that ``$reduce_or`` and ``$reduce_bool`` actually represent the same logic -function. But the HDL frontends generate them in different situations. A -``$reduce_or`` cell is generated when the prefix ``|`` operator is being used. A -``$reduce_bool`` cell is generated when a bit vector is used as a condition in -an ``if``-statement or ``?:``-expression. - -Binary operators -~~~~~~~~~~~~~~~~ - -All binary RTL cells have two input ports ``\A`` and ``\B`` and one output port -``\Y``. They also have the following parameters: - -``\A_SIGNED`` - Set to a non-zero value if the input ``\A`` is signed and therefore - should be sign-extended when needed. - -``\A_WIDTH`` - The width of the input port ``\A``. - -``\B_SIGNED`` - Set to a non-zero value if the input ``\B`` is signed and therefore - should be sign-extended when needed. - -``\B_WIDTH`` - The width of the input port ``\B``. - -``\Y_WIDTH`` - The width of the output port ``\Y``. - -:numref:`tab:CellLib_binary` lists all cells for binary RTL operators. - -.. table:: Cell types for binary operators with their corresponding Verilog expressions. - :name: tab:CellLib_binary - - ======================= ============= ======================= ========= - Verilog Cell Type Verilog Cell Type - ======================= ============= ======================= ========= - :verilog:`Y = A & B` $and :verilog:`Y = A < B` $lt - :verilog:`Y = A | B` $or :verilog:`Y = A <= B` $le - :verilog:`Y = A ^ B` $xor :verilog:`Y = A == B` $eq - :verilog:`Y = A ~^ B` $xnor :verilog:`Y = A != B` $ne - :verilog:`Y = A << B` $shl :verilog:`Y = A >= B` $ge - :verilog:`Y = A >> B` $shr :verilog:`Y = A > B` $gt - :verilog:`Y = A <<< B` $sshl :verilog:`Y = A + B` $add - :verilog:`Y = A >>> B` $sshr :verilog:`Y = A - B` $sub - :verilog:`Y = A && B` $logic_and :verilog:`Y = A * B` $mul - :verilog:`Y = A || B` $logic_or :verilog:`Y = A / B` $div - :verilog:`Y = A === B` $eqx :verilog:`Y = A % B` $mod - :verilog:`Y = A !== B` $nex ``N/A`` $divfloor - :verilog:`Y = A ** B` $pow ``N/A`` $modfloor - ======================= ============= ======================= ========= - -The ``$shl`` and ``$shr`` cells implement logical shifts, whereas the ``$sshl`` -and ``$sshr`` cells implement arithmetic shifts. The ``$shl`` and ``$sshl`` -cells implement the same operation. All four of these cells interpret the second -operand as unsigned, and require ``\B_SIGNED`` to be zero. - -Two additional shift operator cells are available that do not directly -correspond to any operator in Verilog, ``$shift`` and ``$shiftx``. The -``$shift`` cell performs a right logical shift if the second operand is positive -(or unsigned), and a left logical shift if it is negative. The ``$shiftx`` cell -performs the same operation as the ``$shift`` cell, but the vacated bit -positions are filled with undef (x) bits, and corresponds to the Verilog indexed -part-select expression. - -For the binary cells that output a logical value (``$logic_and``, ``$logic_or``, -``$eqx``, ``$nex``, ``$lt``, ``$le``, ``$eq``, ``$ne``, ``$ge``, ``$gt``), when -the ``\Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and -only the least significant bit varies. - -Division and modulo cells are available in two rounding modes. The original -``$div`` and ``$mod`` cells are based on truncating division, and correspond to -the semantics of the verilog ``/`` and ``%`` operators. The ``$divfloor`` and -``$modfloor`` cells represent flooring division and flooring modulo, the latter -of which is also known as "remainder" in several languages. See -:numref:`tab:CellLib_divmod` for a side-by-side comparison between the different -semantics. - -.. table:: Comparison between different rounding modes for division and modulo cells. - :name: tab:CellLib_divmod - - +-----------+--------+-----------+-----------+-----------+-----------+ - | Division | Result | Truncating | Flooring | - +-----------+--------+-----------+-----------+-----------+-----------+ - | | | $div | $mod | $divfloor | $modfloor | - +===========+========+===========+===========+===========+===========+ - | -10 / 3 | -3.3 | -3 | -1 | -4 | 2 | - +-----------+--------+-----------+-----------+-----------+-----------+ - | 10 / -3 | -3.3 | -3 | 1 | -4 | -2 | - +-----------+--------+-----------+-----------+-----------+-----------+ - | -10 / -3 | 3.3 | 3 | -1 | 3 | -1 | - +-----------+--------+-----------+-----------+-----------+-----------+ - | 10 / 3 | 3.3 | 3 | 1 | 3 | 1 | - +-----------+--------+-----------+-----------+-----------+-----------+ - -Multiplexers -~~~~~~~~~~~~ - -Multiplexers are generated by the Verilog HDL frontend for ``?:``-expressions. -Multiplexers are also generated by the proc pass to map the decision trees from -RTLIL::Process objects to logic. - -The simplest multiplexer cell type is ``$mux``. Cells of this type have a -``\WITDH`` parameter and data inputs ``\A`` and ``\B`` and a data output ``\Y``, -all of the specified width. This cell also has a single bit control input -``\S``. If ``\S`` is 0 the value from the input ``\A`` is sent to the output, if -it is 1 the value from the ``\B`` input is sent to the output. So the ``$mux`` -cell implements the function :verilog:`Y = S ? B : A`. - -The ``$pmux`` cell is used to multiplex between many inputs using a one-hot -select signal. Cells of this type have a ``\WIDTH`` and a ``\S_WIDTH`` parameter -and inputs ``\A``, ``\B``, and ``\S`` and an output ``\Y``. The ``\S`` input is -``\S_WIDTH`` bits wide. The ``\A`` input and the output are both ``\WIDTH`` bits -wide and the ``\B`` input is ``\WIDTH*\S_WIDTH`` bits wide. When all bits of -``\S`` are zero, the value from ``\A`` input is sent to the output. If the -:math:`n`\ 'th bit from ``\S`` is set, the value :math:`n`\ 'th ``\WIDTH`` bits -wide slice of the ``\B`` input is sent to the output. When more than one bit -from ``\S`` is set the output is undefined. Cells of this type are used to model -"parallel cases" (defined by using the ``parallel_case`` attribute or detected -by an optimization). - -The ``$tribuf`` cell is used to implement tristate logic. Cells of this type -have a ``\WIDTH`` parameter and inputs ``\A`` and ``\EN`` and an output ``\Y``. The -``\A`` input and ``\Y`` output are ``\WIDTH`` bits wide, and the ``\EN`` input -is one bit wide. When ``\EN`` is 0, the output is not driven. When ``\EN`` is 1, -the value from ``\A`` input is sent to the ``\Y`` output. Therefore, the -``$tribuf`` cell implements the function :verilog:`Y = EN ? A : 'bz`. - -Behavioural code with cascaded if-then-else- and case-statements usually results -in trees of multiplexer cells. Many passes (from various optimizations to FSM -extraction) heavily depend on these multiplexer trees to understand dependencies -between signals. Therefore optimizations should not break these multiplexer -trees (e.g. by replacing a multiplexer between a calculated signal and a -constant zero with an ``$and`` gate). - -Registers -~~~~~~~~~ - -SR-type latches are represented by ``$sr`` cells. These cells have input ports -``\SET`` and ``\CLR`` and an output port ``\Q``. They have the following -parameters: - -``\WIDTH`` - The width of inputs ``\SET`` and ``\CLR`` and output ``\Q``. - -``\SET_POLARITY`` - The set input bits are active-high if this parameter has the value - ``1'b1`` and active-low if this parameter is ``1'b0``. - -``\CLR_POLARITY`` - The reset input bits are active-high if this parameter has the value - ``1'b1`` and active-low if this parameter is ``1'b0``. - -Both set and reset inputs have separate bits for every output bit. When both the -set and reset inputs of an ``$sr`` cell are active for a given bit index, the -reset input takes precedence. - -D-type flip-flops are represented by ``$dff`` cells. These cells have a clock -port ``\CLK``, an input port ``\D`` and an output port ``\Q``. The following -parameters are available for ``$dff`` cells: - -``\WIDTH`` - The width of input ``\D`` and output ``\Q``. - -``\CLK_POLARITY`` - Clock is active on the positive edge if this parameter has the value - ``1'b1`` and on the negative edge if this parameter is ``1'b0``. - -D-type flip-flops with asynchronous reset are represented by ``$adff`` cells. As -the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they -also have a single-bit ``\ARST`` input port for the reset pin and the following -additional two parameters: - -``\ARST_POLARITY`` - The asynchronous reset is active-high if this parameter has the value - ``1'b1`` and active-low if this parameter is ``1'b0``. - -``\ARST_VALUE`` - The state of ``\Q`` will be set to this value when the reset is active. - -Usually these cells are generated by the :cmd:ref:`proc` pass using the -information in the designs RTLIL::Process objects. - -D-type flip-flops with synchronous reset are represented by ``$sdff`` cells. As -the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they -also have a single-bit ``\SRST`` input port for the reset pin and the following -additional two parameters: - -``\SRST_POLARITY`` - The synchronous reset is active-high if this parameter has the value - ``1'b1`` and active-low if this parameter is ``1'b0``. - -``\SRST_VALUE`` - The state of ``\Q`` will be set to this value when the reset is active. - -Note that the ``$adff`` and ``$sdff`` cells can only be used when the reset -value is constant. - -D-type flip-flops with asynchronous load are represented by ``$aldff`` cells. As -the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they -also have a single-bit ``\ALOAD`` input port for the async load enable pin, a -``\AD`` input port with the same width as data for the async load data, and the -following additional parameter: - -``\ALOAD_POLARITY`` - The asynchronous load is active-high if this parameter has the value - ``1'b1`` and active-low if this parameter is ``1'b0``. - -D-type flip-flops with asynchronous set and reset are represented by ``$dffsr`` -cells. As the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In -addition they also have multi-bit ``\SET`` and ``\CLR`` input ports and the -corresponding polarity parameters, like ``$sr`` cells. - -D-type flip-flops with enable are represented by ``$dffe``, ``$adffe``, -``$aldffe``, ``$dffsre``, ``$sdffe``, and ``$sdffce`` cells, which are enhanced -variants of ``$dff``, ``$adff``, ``$aldff``, ``$dffsr``, ``$sdff`` (with reset -over enable) and ``$sdff`` (with enable over reset) cells, respectively. They -have the same ports and parameters as their base cell. In addition they also -have a single-bit ``\EN`` input port for the enable pin and the following -parameter: - -``\EN_POLARITY`` - The enable input is active-high if this parameter has the value ``1'b1`` - and active-low if this parameter is ``1'b0``. - -D-type latches are represented by ``$dlatch`` cells. These cells have an enable -port ``\EN``, an input port ``\D``, and an output port ``\Q``. The following -parameters are available for ``$dlatch`` cells: - -``\WIDTH`` - The width of input ``\D`` and output ``\Q``. - -``\EN_POLARITY`` - The enable input is active-high if this parameter has the value ``1'b1`` - and active-low if this parameter is ``1'b0``. - -The latch is transparent when the ``\EN`` input is active. - -D-type latches with reset are represented by ``$adlatch`` cells. In addition to -``$dlatch`` ports and parameters, they also have a single-bit ``\ARST`` input -port for the reset pin and the following additional parameters: - -``\ARST_POLARITY`` - The asynchronous reset is active-high if this parameter has the value - ``1'b1`` and active-low if this parameter is ``1'b0``. - -``\ARST_VALUE`` - The state of ``\Q`` will be set to this value when the reset is active. - -D-type latches with set and reset are represented by ``$dlatchsr`` cells. In -addition to ``$dlatch`` ports and parameters, they also have multi-bit ``\SET`` -and ``\CLR`` input ports and the corresponding polarity parameters, like ``$sr`` -cells. - -.. _sec:memcells: - -Memories -~~~~~~~~ - -Memories are either represented using ``RTLIL::Memory`` objects, ``$memrd_v2``, -``$memwr_v2``, and ``$meminit_v2`` cells, or by ``$mem_v2`` cells alone. - -In the first alternative the ``RTLIL::Memory`` objects hold the general metadata -for the memory (bit width, size in number of words, etc.) and for each port a -``$memrd_v2`` (read port) or ``$memwr_v2`` (write port) cell is created. Having -individual cells for read and write ports has the advantage that they can be -consolidated using resource sharing passes. In some cases this drastically -reduces the number of required ports on the memory cell. In this alternative, -memory initialization data is represented by ``$meminit_v2`` cells, which allow -delaying constant folding for initialization addresses and data until after the -frontend finishes. - -The ``$memrd_v2`` cells have a clock input ``\CLK``, an enable input ``\EN``, an -address input ``\ADDR``, a data output ``\DATA``, an asynchronous reset input -``\ARST``, and a synchronous reset input ``\SRST``. They also have the following -parameters: - -``\MEMID`` - The name of the ``RTLIL::Memory`` object that is associated with this read - port. - -``\ABITS`` - The number of address bits (width of the ``\ADDR`` input port). - -``\WIDTH`` - The number of data bits (width of the ``\DATA`` output port). Note that - this may be a power-of-two multiple of the underlying memory's width -- - such ports are called wide ports and access an aligned group of cells at - once. In this case, the corresponding low bits of ``\ADDR`` must be - tied to 0. - -``\CLK_ENABLE`` - When this parameter is non-zero, the clock is used. Otherwise this read - port is asynchronous and the ``\CLK`` input is not used. - -``\CLK_POLARITY`` - Clock is active on the positive edge if this parameter has the value - ``1'b1`` and on the negative edge if this parameter is ``1'b0``. - -``\TRANSPARENCY_MASK`` - This parameter is a bitmask of write ports that this read port is - transparent with. The bits of this parameter are indexed by the write - port's ``\PORTID`` parameter. Transparency can only be enabled between - synchronous ports sharing a clock domain. When transparency is enabled - for a given port pair, a read and write to the same address in the same - cycle will return the new value. Otherwise the old value is returned. - -``\COLLISION_X_MASK`` - This parameter is a bitmask of write ports that have undefined collision - behavior with this port. The bits of this parameter are indexed by the - write port's ``\PORTID`` parameter. This behavior can only be enabled - between synchronous ports sharing a clock domain. When undefined - collision is enabled for a given port pair, a read and write to the same - address in the same cycle will return the undefined (all-X) value.This - option is exclusive (for a given port pair) with the transparency - option. - -``\ARST_VALUE`` - Whenever the ``\ARST`` input is asserted, the data output will be reset - to this value. Only used for synchronous ports. - -``\SRST_VALUE`` - Whenever the ``\SRST`` input is synchronously asserted, the data output - will be reset to this value. Only used for synchronous ports. - -``\INIT_VALUE`` - The initial value of the data output, for synchronous ports. - -``\CE_OVER_SRST`` - If this parameter is non-zero, the ``\SRST`` input is only recognized - when ``\EN`` is true. Otherwise, ``\SRST`` is recognized regardless of - ``\EN``. - -The ``$memwr_v2`` cells have a clock input ``\CLK``, an enable input ``\EN`` -(one enable bit for each data bit), an address input ``\ADDR`` and a data input -``\DATA``. They also have the following parameters: - -``\MEMID`` - The name of the ``RTLIL::Memory`` object that is associated with this write - port. - -``\ABITS`` - The number of address bits (width of the ``\ADDR`` input port). - -``\WIDTH`` - The number of data bits (width of the ``\DATA`` output port). Like with - ``$memrd_v2`` cells, the width is allowed to be any power-of-two - multiple of memory width, with the corresponding restriction on address. - -``\CLK_ENABLE`` - When this parameter is non-zero, the clock is used. Otherwise this write - port is asynchronous and the ``\CLK`` input is not used. - -``\CLK_POLARITY`` - Clock is active on positive edge if this parameter has the value - ``1'b1`` and on the negative edge if this parameter is ``1'b0``. - -``\PORTID`` - An identifier for this write port, used to index write port bit mask - parameters. - -``\PRIORITY_MASK`` - This parameter is a bitmask of write ports that this write port has priority - over in case of writing to the same address. The bits of this parameter are - indexed by the other write port's ``\PORTID`` parameter. Write ports can - only have priority over write ports with lower port ID. When two ports write - to the same address and neither has priority over the other, the result is - undefined. Priority can only be set between two synchronous ports sharing - the same clock domain. - -The ``$meminit_v2`` cells have an address input ``\ADDR``, a data input -``\DATA``, with the width of the ``\DATA`` port equal to ``\WIDTH`` parameter -times ``\WORDS`` parameter, and a bit enable mask input ``\EN`` with width equal -to ``\WIDTH`` parameter. All three of the inputs must resolve to a constant for -synthesis to succeed. - -``\MEMID`` - The name of the ``RTLIL::Memory`` object that is associated with this - initialization cell. - -``\ABITS`` - The number of address bits (width of the ``\ADDR`` input port). - -``\WIDTH`` - The number of data bits per memory location. - -``\WORDS`` - The number of consecutive memory locations initialized by this cell. - -``\PRIORITY`` - The cell with the higher integer value in this parameter wins an - initialization conflict. - -The HDL frontend models a memory using ``RTLIL::Memory`` objects and -asynchronous ``$memrd_v2`` and ``$memwr_v2`` cells. The :cmd:ref:`memory` pass -(i.e. its various sub-passes) migrates ``$dff`` cells into the ``$memrd_v2`` and -``$memwr_v2`` cells making them synchronous, then converts them to a single -``$mem_v2`` cell and (optionally) maps this cell type to ``$dff`` cells for the -individual words and multiplexer-based address decoders for the read and write -interfaces. When the last step is disabled or not possible, a ``$mem_v2`` cell -is left in the design. - -The ``$mem_v2`` cell provides the following parameters: - -``\MEMID`` - The name of the original ``RTLIL::Memory`` object that became this - ``$mem_v2`` cell. - -``\SIZE`` - The number of words in the memory. - -``\ABITS`` - The number of address bits. - -``\WIDTH`` - The number of data bits per word. - -``\INIT`` - The initial memory contents. - -``\RD_PORTS`` - The number of read ports on this memory cell. - -``\RD_WIDE_CONTINUATION`` - This parameter is ``\RD_PORTS`` bits wide, containing a bitmask of - "wide continuation" read ports. Such ports are used to represent the - extra data bits of wide ports in the combined cell, and must have all - control signals identical with the preceding port, except for address, - which must have the proper sub-cell address encoded in the low bits. - -``\RD_CLK_ENABLE`` - This parameter is ``\RD_PORTS`` bits wide, containing a clock enable bit - for each read port. - -``\RD_CLK_POLARITY`` - This parameter is ``\RD_PORTS`` bits wide, containing a clock polarity - bit for each read port. - -``\RD_TRANSPARENCY_MASK`` - This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a - concatenation of all ``\TRANSPARENCY_MASK`` values of the original - ``$memrd_v2`` cells. - -``\RD_COLLISION_X_MASK`` - This parameter is ``\RD_PORTS*\WR_PORTS`` bits wide, containing a - concatenation of all ``\COLLISION_X_MASK`` values of the original - ``$memrd_v2`` cells. - -``\RD_CE_OVER_SRST`` - This parameter is ``\RD_PORTS`` bits wide, determining relative - synchronous reset and enable priority for each read port. - -``\RD_INIT_VALUE`` - This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the initial - value for each synchronous read port. - -``\RD_ARST_VALUE`` - This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the - asynchronous reset value for each synchronous read port. - -``\RD_SRST_VALUE`` - This parameter is ``\RD_PORTS*\WIDTH`` bits wide, containing the - synchronous reset value for each synchronous read port. - -``\WR_PORTS`` - The number of write ports on this memory cell. - -``\WR_WIDE_CONTINUATION`` - This parameter is ``\WR_PORTS`` bits wide, containing a bitmask of - "wide continuation" write ports. - -``\WR_CLK_ENABLE`` - This parameter is ``\WR_PORTS`` bits wide, containing a clock enable bit - for each write port. - -``\WR_CLK_POLARITY`` - This parameter is ``\WR_PORTS`` bits wide, containing a clock polarity - bit for each write port. - -``\WR_PRIORITY_MASK`` - This parameter is ``\WR_PORTS*\WR_PORTS`` bits wide, containing a - concatenation of all ``\PRIORITY_MASK`` values of the original - ``$memwr_v2`` cells. - -The ``$mem_v2`` cell has the following ports: - -``\RD_CLK`` - This input is ``\RD_PORTS`` bits wide, containing all clock signals for - the read ports. - -``\RD_EN`` - This input is ``\RD_PORTS`` bits wide, containing all enable signals for - the read ports. - -``\RD_ADDR`` - This input is ``\RD_PORTS*\ABITS`` bits wide, containing all address - signals for the read ports. - -``\RD_DATA`` - This output is ``\RD_PORTS*\WIDTH`` bits wide, containing all data - signals for the read ports. - -``\RD_ARST`` - This input is ``\RD_PORTS`` bits wide, containing all asynchronous reset - signals for the read ports. - -``\RD_SRST`` - This input is ``\RD_PORTS`` bits wide, containing all synchronous reset - signals for the read ports. - -``\WR_CLK`` - This input is ``\WR_PORTS`` bits wide, containing all clock signals for - the write ports. - -``\WR_EN`` - This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all enable - signals for the write ports. - -``\WR_ADDR`` - This input is ``\WR_PORTS*\ABITS`` bits wide, containing all address - signals for the write ports. - -``\WR_DATA`` - This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all data - signals for the write ports. - -The :cmd:ref:`memory_collect` pass can be used to convert discrete -``$memrd_v2``, ``$memwr_v2``, and ``$meminit_v2`` cells belonging to the same -memory to a single ``$mem_v2`` cell, whereas the :cmd:ref:`memory_unpack` pass -performs the inverse operation. The :cmd:ref:`memory_dff` pass can combine -asynchronous memory ports that are fed by or feeding registers into synchronous -memory ports. The :cmd:ref:`memory_bram` pass can be used to recognize -``$mem_v2`` cells that can be implemented with a block RAM resource on an FPGA. -The :cmd:ref:`memory_map` pass can be used to implement ``$mem_v2`` cells as -basic logic: word-wide DFFs and address decoders. - -Finite state machines -~~~~~~~~~~~~~~~~~~~~~ - -Add a brief description of the ``$fsm`` cell type. - -Coarse arithmetics -~~~~~~~~~~~~~~~~~~~~~ - -The ``$macc`` cell type represents a generalized multiply and accumulate operation. The cell is purely combinational. It outputs the result of summing up a sequence of products and other injected summands. - -.. code-block:: - - Y = 0 +- a0factor1 * a0factor2 +- a1factor1 * a1factor2 +- ... - + B[0] + B[1] + ... - -The A port consists of concatenated pairs of multiplier inputs ("factors"). -A zero length factor2 acts as a constant 1, turning factor1 into a simple summand. - -In this pseudocode, ``u(foo)`` means an unsigned int that's foo bits long. - -.. code-block:: - - struct A { - u(CONFIG.mul_info[0].factor1_len) a0factor1; - u(CONFIG.mul_info[0].factor2_len) a0factor2; - u(CONFIG.mul_info[1].factor1_len) a1factor1; - u(CONFIG.mul_info[1].factor2_len) a1factor2; - ... - }; - -The cell's ``CONFIG`` parameter determines the layout of cell port ``A``. -The CONFIG parameter carries the following information: - -.. code-block:: - - struct CONFIG { - u4 num_bits; - struct mul_info { - bool is_signed; - bool is_subtract; - u(num_bits) factor1_len; - u(num_bits) factor2_len; - }[num_ports]; - }; - -B is an array of concatenated 1-bit-wide unsigned integers to also be summed up. - -Arbitrary logic functions -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``$lut`` cell type implements a single-output LUT (lookup table). -It implements an arbitrary logic function with its ``\LUT`` parameter to map -input port ``\A`` to values of ``\Y`` output port values. -In psuedocode: ``Y = \LUT[A]``. -``\A`` has width set by parameter ``\WIDTH`` and ``\Y`` has a width of 1. -Every logic function with a single bit output has a unique ``$lut`` -representation. - -The ``$sop`` cell type implements a sum-of-products expression, also known -as disjunctive normal form (DNF). It implements an arbitrary logic function. -Its structure mimics a programmable logic array (PLA). -Output port ``\Y`` is the sum of products of the bits of the input port ``\A`` -as defined by parameter ``\TABLE``. ``\A`` is ``\WIDTH`` bits wide. -The number of products in the sum is set by parameter ``\DEPTH``, and each -product has two bits for each input bit - for the presence of the -unnegated and negated version of said input bit in the product. -Therefore the ``\TABLE`` parameter holds ``2 * \WIDTH * \DEPTH`` bits. - -For example: - -Let ``\WIDTH`` be 3. We would like to represent ``\Y =~\A[0] + \A[1]~\A[2]``. -There are 2 products to be summed, so ``\DEPTH`` shall be 2. - -.. code-block:: - - ~A[2]-----+ - A[2]----+| - ~A[1]---+|| - A[1]--+||| - ~A[0]-+|||| - A[0]+||||| - |||||| product formula - 010000 ~\A[0] - 001001 \A[1]~\A[2] - -So the value of ``\TABLE`` will become ``010000001001``. - -Any logic function with a single bit output can be represented with -``$sop`` but may have variously minimized or ordered summands represented -in the ``\TABLE`` values. - -Specify rules -~~~~~~~~~~~~~ - -Add information about ``$specify2``, ``$specify3``, and ``$specrule`` cells. - -Formal verification cells -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Add information about ``$check``, ``$assert``, ``$assume``, ``$live``, ``$fair``, -``$cover``, ``$equiv``, ``$initstate``, ``$anyconst``, ``$anyseq``, -``$anyinit``, ``$allconst``, ``$allseq`` cells. - -Add information about ``$ff`` and ``$_FF_`` cells. - -Debugging cells -~~~~~~~~~~~~~~~ - -The ``$print`` cell is used to log the values of signals, akin to (and -translatable to) the ``$display`` and ``$write`` family of tasks in Verilog. It -has the following parameters: - -``\FORMAT`` - The internal format string. The syntax is described below. - -``\ARGS_WIDTH`` - The width (in bits) of the signal on the ``\ARGS`` port. - -``\TRG_ENABLE`` - True if triggered on specific signals defined in ``\TRG``; false if - triggered whenever ``\ARGS`` or ``\EN`` change and ``\EN`` is 1. - -If ``\TRG_ENABLE`` is true, the following parameters also apply: - -``\TRG_WIDTH`` - The number of bits in the ``\TRG`` port. - -``\TRG_POLARITY`` - For each bit in ``\TRG``, 1 if that signal is positive-edge triggered, 0 if - negative-edge triggered. - -``\PRIORITY`` - When multiple ``$print`` or ``$$check`` cells fire on the same trigger, they\ - execute in descending priority order. - -Ports: - -``\TRG`` - The signals that control when this ``$print`` cell is triggered. - If the width of this port is zero and ``\TRG_ENABLE`` is true, the cell is - triggered during initial evaluation (time zero) only. - -``\EN`` - Enable signal for the whole cell. - -``\ARGS`` - The values to be displayed, in format string order. - -Format string syntax -^^^^^^^^^^^^^^^^^^^^ - -The format string syntax resembles Python f-strings. Regular text is passed -through unchanged until a format specifier is reached, starting with a ``{``. - -Format specifiers have the following syntax. Unless noted, all items are -required: - -``{`` - Denotes the start of the format specifier. - -size - Signal size in bits; this many bits are consumed from the ``\ARGS`` port by - this specifier. - -``:`` - Separates the size from the remaining items. - -justify - ``>`` for right-justified, ``<`` for left-justified. - -padding - ``0`` for zero-padding, or a space for space-padding. - -width\ *?* - (optional) The number of characters wide to pad to. - -base - * ``b`` for base-2 integers (binary) - * ``o`` for base-8 integers (octal) - * ``d`` for base-10 integers (decimal) - * ``h`` for base-16 integers (hexadecimal) - * ``c`` for ASCII characters/strings - * ``t`` and ``r`` for simulation time (corresponding to :verilog:`$time` and :verilog:`$realtime`) - -For integers, this item may follow: - -``+``\ *?* - (optional, decimals only) Include a leading plus for non-negative numbers. - This can assist with symmetry with negatives in tabulated output. - -signedness - ``u`` for unsigned, ``s`` for signed. This distinction is only respected - when rendering decimals. - -ASCII characters/strings have no special options, but the signal size must be -divisible by 8. - -For simulation time, the signal size must be zero. - -Finally: - -``}`` - Denotes the end of the format specifier. - -Some example format specifiers: - -+ ``{8:>02hu}`` - 8-bit unsigned integer rendered as hexadecimal, - right-justified, zero-padded to 2 characters wide. -+ ``{32:< 15d+s}`` - 32-bit signed integer rendered as decimal, left-justified, - space-padded to 15 characters wide, positive values prefixed with ``+``. -+ ``{16:< 10hu}`` - 16-bit unsigned integer rendered as hexadecimal, - left-justified, space-padded to 10 characters wide. -+ ``{0:>010t}`` - simulation time, right-justified, zero-padded to 10 characters - wide. - -To include literal ``{`` and ``}`` characters in your format string, use ``{{`` -and ``}}`` respectively. - -It is an error for a format string to consume more or less bits from ``\ARGS`` -than the port width. - -Values are never truncated, regardless of the specified width. - -Note that further restrictions on allowable combinations of options may apply -depending on the backend used. - -For example, Verilog does not have a format specifier that allows zero-padding a -string (i.e. more than 1 ASCII character), though zero-padding a single -character is permitted. - -Thus, while the RTLIL format specifier ``{8:>02c}`` translates to ``%02c``, -``{16:>02c}`` cannot be represented in Verilog and will fail to emit. In this -case, ``{16:> 02c}`` must be used, which translates to ``%2s``. - -.. _sec:celllib_gates: - -Gates ------ - -For gate level logic networks, fixed function single bit cells are used that do -not provide any parameters. - -Simulation models for these cells can be found in the file -techlibs/common/simcells.v in the Yosys source tree. - -.. table:: Cell types for gate level logic networks (main list) - :name: tab:CellLib_gates - - ======================================= ============ - Verilog Cell Type - ======================================= ============ - :verilog:`Y = A` $_BUF_ - :verilog:`Y = ~A` $_NOT_ - :verilog:`Y = A & B` $_AND_ - :verilog:`Y = ~(A & B)` $_NAND_ - :verilog:`Y = A & ~B` $_ANDNOT_ - :verilog:`Y = A | B` $_OR_ - :verilog:`Y = ~(A | B)` $_NOR_ - :verilog:`Y = A | ~B` $_ORNOT_ - :verilog:`Y = A ^ B` $_XOR_ - :verilog:`Y = ~(A ^ B)` $_XNOR_ - :verilog:`Y = ~((A & B) | C)` $_AOI3_ - :verilog:`Y = ~((A | B) & C)` $_OAI3_ - :verilog:`Y = ~((A & B) | (C & D))` $_AOI4_ - :verilog:`Y = ~((A | B) & (C | D))` $_OAI4_ - :verilog:`Y = S ? B : A` $_MUX_ - :verilog:`Y = ~(S ? B : A)` $_NMUX_ - (see below) $_MUX4_ - (see below) $_MUX8_ - (see below) $_MUX16_ - :verilog:`Y = EN ? A : 1'bz` $_TBUF_ - :verilog:`always @(negedge C) Q <= D` $_DFF_N_ - :verilog:`always @(posedge C) Q <= D` $_DFF_P_ - :verilog:`always @* if (!E) Q <= D` $_DLATCH_N_ - :verilog:`always @* if (E) Q <= D` $_DLATCH_P_ - ======================================= ============ - -.. table:: Cell types for gate level logic networks (FFs with reset) - :name: tab:CellLib_gates_adff - - ================== ============== ============== ======================= - :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` Cell Type - ================== ============== ============== ======================= - :verilog:`negedge` ``0`` ``0`` $_DFF_NN0_, $_SDFF_NN0_ - :verilog:`negedge` ``0`` ``1`` $_DFF_NN1_, $_SDFF_NN1_ - :verilog:`negedge` ``1`` ``0`` $_DFF_NP0_, $_SDFF_NP0_ - :verilog:`negedge` ``1`` ``1`` $_DFF_NP1_, $_SDFF_NP1_ - :verilog:`posedge` ``0`` ``0`` $_DFF_PN0_, $_SDFF_PN0_ - :verilog:`posedge` ``0`` ``1`` $_DFF_PN1_, $_SDFF_PN1_ - :verilog:`posedge` ``1`` ``0`` $_DFF_PP0_, $_SDFF_PP0_ - :verilog:`posedge` ``1`` ``1`` $_DFF_PP1_, $_SDFF_PP1_ - ================== ============== ============== ======================= - - -.. table:: Cell types for gate level logic networks (FFs with enable) - :name: tab:CellLib_gates_dffe - - ================== ============= =========== - :math:`ClkEdge` :math:`EnLvl` Cell Type - ================== ============= =========== - :verilog:`negedge` ``0`` $_DFFE_NN_ - :verilog:`negedge` ``1`` $_DFFE_NP_ - :verilog:`posedge` ``0`` $_DFFE_PN_ - :verilog:`posedge` ``1`` $_DFFE_PP_ - ================== ============= =========== - - -.. table:: Cell types for gate level logic networks (FFs with reset and enable) - :name: tab:CellLib_gates_adffe - - ================== ============== ============== ============= =========================================== - :math:`ClkEdge` :math:`RstLvl` :math:`RstVal` :math:`EnLvl` Cell Type - ================== ============== ============== ============= =========================================== - :verilog:`negedge` ``0`` ``0`` ``0`` $_DFFE_NN0N_, $_SDFFE_NN0N_, $_SDFFCE_NN0N_ - :verilog:`negedge` ``0`` ``0`` ``1`` $_DFFE_NN0P_, $_SDFFE_NN0P_, $_SDFFCE_NN0P_ - :verilog:`negedge` ``0`` ``1`` ``0`` $_DFFE_NN1N_, $_SDFFE_NN1N_, $_SDFFCE_NN1N_ - :verilog:`negedge` ``0`` ``1`` ``1`` $_DFFE_NN1P_, $_SDFFE_NN1P_, $_SDFFCE_NN1P_ - :verilog:`negedge` ``1`` ``0`` ``0`` $_DFFE_NP0N_, $_SDFFE_NP0N_, $_SDFFCE_NP0N_ - :verilog:`negedge` ``1`` ``0`` ``1`` $_DFFE_NP0P_, $_SDFFE_NP0P_, $_SDFFCE_NP0P_ - :verilog:`negedge` ``1`` ``1`` ``0`` $_DFFE_NP1N_, $_SDFFE_NP1N_, $_SDFFCE_NP1N_ - :verilog:`negedge` ``1`` ``1`` ``1`` $_DFFE_NP1P_, $_SDFFE_NP1P_, $_SDFFCE_NP1P_ - :verilog:`posedge` ``0`` ``0`` ``0`` $_DFFE_PN0N_, $_SDFFE_PN0N_, $_SDFFCE_PN0N_ - :verilog:`posedge` ``0`` ``0`` ``1`` $_DFFE_PN0P_, $_SDFFE_PN0P_, $_SDFFCE_PN0P_ - :verilog:`posedge` ``0`` ``1`` ``0`` $_DFFE_PN1N_, $_SDFFE_PN1N_, $_SDFFCE_PN1N_ - :verilog:`posedge` ``0`` ``1`` ``1`` $_DFFE_PN1P_, $_SDFFE_PN1P_, $_SDFFCE_PN1P_ - :verilog:`posedge` ``1`` ``0`` ``0`` $_DFFE_PP0N_, $_SDFFE_PP0N_, $_SDFFCE_PP0N_ - :verilog:`posedge` ``1`` ``0`` ``1`` $_DFFE_PP0P_, $_SDFFE_PP0P_, $_SDFFCE_PP0P_ - :verilog:`posedge` ``1`` ``1`` ``0`` $_DFFE_PP1N_, $_SDFFE_PP1N_, $_SDFFCE_PP1N_ - :verilog:`posedge` ``1`` ``1`` ``1`` $_DFFE_PP1P_, $_SDFFE_PP1P_, $_SDFFCE_PP1P_ - ================== ============== ============== ============= =========================================== - -.. table:: Cell types for gate level logic networks (FFs with set and reset) - :name: tab:CellLib_gates_dffsr - - ================== ============== ============== ============ - :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` Cell Type - ================== ============== ============== ============ - :verilog:`negedge` ``0`` ``0`` $_DFFSR_NNN_ - :verilog:`negedge` ``0`` ``1`` $_DFFSR_NNP_ - :verilog:`negedge` ``1`` ``0`` $_DFFSR_NPN_ - :verilog:`negedge` ``1`` ``1`` $_DFFSR_NPP_ - :verilog:`posedge` ``0`` ``0`` $_DFFSR_PNN_ - :verilog:`posedge` ``0`` ``1`` $_DFFSR_PNP_ - :verilog:`posedge` ``1`` ``0`` $_DFFSR_PPN_ - :verilog:`posedge` ``1`` ``1`` $_DFFSR_PPP_ - ================== ============== ============== ============ - - -.. table:: Cell types for gate level logic networks (FFs with set and reset and enable) - :name: tab:CellLib_gates_dffsre - - ================== ============== ============== ============= ============== - :math:`ClkEdge` :math:`SetLvl` :math:`RstLvl` :math:`EnLvl` Cell Type - ================== ============== ============== ============= ============== - :verilog:`negedge` ``0`` ``0`` ``0`` $_DFFSRE_NNNN_ - :verilog:`negedge` ``0`` ``0`` ``1`` $_DFFSRE_NNNP_ - :verilog:`negedge` ``0`` ``1`` ``0`` $_DFFSRE_NNPN_ - :verilog:`negedge` ``0`` ``1`` ``1`` $_DFFSRE_NNPP_ - :verilog:`negedge` ``1`` ``0`` ``0`` $_DFFSRE_NPNN_ - :verilog:`negedge` ``1`` ``0`` ``1`` $_DFFSRE_NPNP_ - :verilog:`negedge` ``1`` ``1`` ``0`` $_DFFSRE_NPPN_ - :verilog:`negedge` ``1`` ``1`` ``1`` $_DFFSRE_NPPP_ - :verilog:`posedge` ``0`` ``0`` ``0`` $_DFFSRE_PNNN_ - :verilog:`posedge` ``0`` ``0`` ``1`` $_DFFSRE_PNNP_ - :verilog:`posedge` ``0`` ``1`` ``0`` $_DFFSRE_PNPN_ - :verilog:`posedge` ``0`` ``1`` ``1`` $_DFFSRE_PNPP_ - :verilog:`posedge` ``1`` ``0`` ``0`` $_DFFSRE_PPNN_ - :verilog:`posedge` ``1`` ``0`` ``1`` $_DFFSRE_PPNP_ - :verilog:`posedge` ``1`` ``1`` ``0`` $_DFFSRE_PPPN_ - :verilog:`posedge` ``1`` ``1`` ``1`` $_DFFSRE_PPPP_ - ================== ============== ============== ============= ============== - - -.. table:: Cell types for gate level logic networks (latches with reset) - :name: tab:CellLib_gates_adlatch - - ============= ============== ============== ============= - :math:`EnLvl` :math:`RstLvl` :math:`RstVal` Cell Type - ============= ============== ============== ============= - ``0`` ``0`` ``0`` $_DLATCH_NN0_ - ``0`` ``0`` ``1`` $_DLATCH_NN1_ - ``0`` ``1`` ``0`` $_DLATCH_NP0_ - ``0`` ``1`` ``1`` $_DLATCH_NP1_ - ``1`` ``0`` ``0`` $_DLATCH_PN0_ - ``1`` ``0`` ``1`` $_DLATCH_PN1_ - ``1`` ``1`` ``0`` $_DLATCH_PP0_ - ``1`` ``1`` ``1`` $_DLATCH_PP1_ - ============= ============== ============== ============= - - -.. table:: Cell types for gate level logic networks (latches with set and reset) - :name: tab:CellLib_gates_dlatchsr - - ============= ============== ============== =============== - :math:`EnLvl` :math:`SetLvl` :math:`RstLvl` Cell Type - ============= ============== ============== =============== - ``0`` ``0`` ``0`` $_DLATCHSR_NNN_ - ``0`` ``0`` ``1`` $_DLATCHSR_NNP_ - ``0`` ``1`` ``0`` $_DLATCHSR_NPN_ - ``0`` ``1`` ``1`` $_DLATCHSR_NPP_ - ``1`` ``0`` ``0`` $_DLATCHSR_PNN_ - ``1`` ``0`` ``1`` $_DLATCHSR_PNP_ - ``1`` ``1`` ``0`` $_DLATCHSR_PPN_ - ``1`` ``1`` ``1`` $_DLATCHSR_PPP_ - ============= ============== ============== =============== - - - -.. table:: Cell types for gate level logic networks (SR latches) - :name: tab:CellLib_gates_sr - - ============== ============== ========= - :math:`SetLvl` :math:`RstLvl` Cell Type - ============== ============== ========= - ``0`` ``0`` $_SR_NN_ - ``0`` ``1`` $_SR_NP_ - ``1`` ``0`` $_SR_PN_ - ``1`` ``1`` $_SR_PP_ - ============== ============== ========= - - -Tables :numref:`%s `, :numref:`%s `, -:numref:`%s `, :numref:`%s `, -:numref:`%s `, :numref:`%s `, -:numref:`%s `, :numref:`%s -` and :numref:`%s ` list all -cell types used for gate level logic. The cell types ``$_BUF_``, ``$_NOT_``, -``$_AND_``, ``$_NAND_``, ``$_ANDNOT_``, ``$_OR_``, ``$_NOR_``, ``$_ORNOT_``, -``$_XOR_``, ``$_XNOR_``, ``$_AOI3_``, ``$_OAI3_``, ``$_AOI4_``, ``$_OAI4_``, -``$_MUX_``, ``$_MUX4_``, ``$_MUX8_``, ``$_MUX16_`` and ``$_NMUX_`` are used to -model combinatorial logic. The cell type ``$_TBUF_`` is used to model tristate -logic. - -The ``$_MUX4_``, ``$_MUX8_`` and ``$_MUX16_`` cells are used to model wide -muxes, and correspond to the following Verilog code: - -.. code-block:: verilog - :force: - - // $_MUX4_ - assign Y = T ? (S ? D : C) : - (S ? B : A); - // $_MUX8_ - assign Y = U ? T ? (S ? H : G) : - (S ? F : E) : - T ? (S ? D : C) : - (S ? B : A); - // $_MUX16_ - assign Y = V ? U ? T ? (S ? P : O) : - (S ? N : M) : - T ? (S ? L : K) : - (S ? J : I) : - U ? T ? (S ? H : G) : - (S ? F : E) : - T ? (S ? D : C) : - (S ? B : A); - -The cell types ``$_DFF_N_`` and ``$_DFF_P_`` represent d-type flip-flops. - -The cell types ``$_DFFE_[NP][NP]_`` implement d-type flip-flops with enable. The -values in the table for these cell types relate to the following Verilog code -template. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C) - if (EN == EN_LVL) - Q <= D; - -The cell types ``$_DFF_[NP][NP][01]_`` implement d-type flip-flops with -asynchronous reset. The values in the table for these cell types relate to the -following Verilog code template, where ``RST_EDGE`` is ``posedge`` if -``RST_LVL`` if ``1``, and ``negedge`` otherwise. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C, RST_EDGE R) - if (R == RST_LVL) - Q <= RST_VAL; - else - Q <= D; - -The cell types ``$_SDFF_[NP][NP][01]_`` implement d-type flip-flops with -synchronous reset. The values in the table for these cell types relate to the -following Verilog code template: - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C) - if (R == RST_LVL) - Q <= RST_VAL; - else - Q <= D; - -The cell types ``$_DFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with -asynchronous reset and enable. The values in the table for these cell types -relate to the following Verilog code template, where ``RST_EDGE`` is -``posedge`` if ``RST_LVL`` if ``1``, and ``negedge`` otherwise. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C, RST_EDGE R) - if (R == RST_LVL) - Q <= RST_VAL; - else if (EN == EN_LVL) - Q <= D; - -The cell types ``$_SDFFE_[NP][NP][01][NP]_`` implement d-type flip-flops with -synchronous reset and enable, with reset having priority over enable. The values -in the table for these cell types relate to the following Verilog code template: - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C) - if (R == RST_LVL) - Q <= RST_VAL; - else if (EN == EN_LVL) - Q <= D; - -The cell types ``$_SDFFCE_[NP][NP][01][NP]_`` implement d-type flip-flops with -synchronous reset and enable, with enable having priority over reset. The values -in the table for these cell types relate to the following Verilog code template: - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C) - if (EN == EN_LVL) - if (R == RST_LVL) - Q <= RST_VAL; - else - Q <= D; - -The cell types ``$_DFFSR_[NP][NP][NP]_`` implement d-type flip-flops with -asynchronous set and reset. The values in the table for these cell types relate -to the following Verilog code template, where ``RST_EDGE`` is ``posedge`` if -``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` is ``posedge`` -if ``SET_LVL`` if ``1``, ``negedge`` otherwise. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S) - if (R == RST_LVL) - Q <= 0; - else if (S == SET_LVL) - Q <= 1; - else - Q <= D; - -The cell types ``$_DFFSRE_[NP][NP][NP][NP]_`` implement d-type flip-flops with -asynchronous set and reset and enable. The values in the table for these cell -types relate to the following Verilog code template, where ``RST_EDGE`` is -``posedge`` if ``RST_LVL`` if ``1``, ``negedge`` otherwise, and ``SET_EDGE`` -is ``posedge`` if ``SET_LVL`` if ``1``, ``negedge`` otherwise. - -.. code-block:: verilog - :force: - - always @(CLK_EDGE C, RST_EDGE R, SET_EDGE S) - if (R == RST_LVL) - Q <= 0; - else if (S == SET_LVL) - Q <= 1; - else if (E == EN_LVL) - Q <= D; - -The cell types ``$_DLATCH_N_`` and ``$_DLATCH_P_`` represent d-type latches. - -The cell types ``$_DLATCH_[NP][NP][01]_`` implement d-type latches with reset. -The values in the table for these cell types relate to the following Verilog -code template: - -.. code-block:: verilog - :force: - - always @* - if (R == RST_LVL) - Q <= RST_VAL; - else if (E == EN_LVL) - Q <= D; - -The cell types ``$_DLATCHSR_[NP][NP][NP]_`` implement d-type latches with set -and reset. The values in the table for these cell types relate to the following -Verilog code template: - -.. code-block:: verilog - :force: - - always @* - if (R == RST_LVL) - Q <= 0; - else if (S == SET_LVL) - Q <= 1; - else if (E == EN_LVL) - Q <= D; - -The cell types ``$_SR_[NP][NP]_`` implement sr-type latches. The values in the -table for these cell types relate to the following Verilog code template: - -.. code-block:: verilog - :force: - - always @* - if (R == RST_LVL) - Q <= 0; - else if (S == SET_LVL) - Q <= 1; - -In most cases gate level logic networks are created from RTL networks using the -techmap pass. The flip-flop cells from the gate level logic network can be -mapped to physical flip-flop cells from a Liberty file using the dfflibmap pass. -The combinatorial logic cells can be mapped to physical cells from a Liberty -file via ABC using the abc pass. - -.. todo:: Add information about ``$slice`` and ``$concat`` cells. - -.. todo:: Add information about ``$alu``, ``$fa``, and ``$lcu`` cells. - -.. todo:: Add information about ``$demux`` cell. \ No newline at end of file diff --git a/docs/source/yosys_internals/formats/index.rst b/docs/source/yosys_internals/formats/index.rst index c187a8238..611370ebc 100644 --- a/docs/source/yosys_internals/formats/index.rst +++ b/docs/source/yosys_internals/formats/index.rst @@ -1,13 +1,59 @@ Internal formats ================ -.. todo:: brief overview for the internal formats index +Yosys uses two different internal formats. The first is used to store an +abstract syntax tree (AST) of a Verilog input file. This format is simply called +AST and is generated by the Verilog Frontend. This data structure is consumed by +a subsystem called AST Frontend [1]_. This AST Frontend then generates a design +in Yosys' main internal format, the +Register-Transfer-Level-Intermediate-Language (RTLIL) representation. It does +that by first performing a number of simplifications within the AST +representation and then generating RTLIL from the simplified AST data structure. + +The RTLIL representation is used by all passes as input and outputs. This has +the following advantages over using different representational formats between +different passes: + +- The passes can be rearranged in a different order and passes can be removed + or inserted. + +- Passes can simply pass-thru the parts of the design they don't change without + the need to convert between formats. In fact Yosys passes output the same + data structure they received as input and performs all changes in place. + +- All passes use the same interface, thus reducing the effort required to + understand a pass when reading the Yosys source code, e.g. when adding + additional features. + +The RTLIL representation is basically a netlist representation with the +following additional features: + +- An internal cell library with fixed-function cells to represent RTL datapath + and register cells as well as logical gate-level cells (single-bit gates and + registers). + +- Support for multi-bit values that can use individual bits from wires as well + as constant bits to represent coarse-grain netlists. + +- Support for basic behavioural constructs (if-then-else structures and + multi-case switches with a sensitivity list for updating the outputs). + +- Support for multi-port memories. + +The use of RTLIL also has the disadvantage of having a very powerful format +between all passes, even when doing gate-level synthesis where the more advanced +features are not needed. In order to reduce complexity for passes that operate +on a low-level representation, these passes check the features used in the input +RTLIL and fail to run when unsupported high-level constructs are used. In such +cases a pass that transforms the higher-level constructs to lower-level +constructs must be called from the synthesis script first. .. toctree:: - :maxdepth: 3 + :maxdepth: 3 - overview - rtlil_rep - rtlil_text - cell_library + rtlil_rep + +.. [1] + In Yosys the term pass is only used to refer to commands that operate on the + RTLIL data structure. diff --git a/docs/source/yosys_internals/formats/overview.rst b/docs/source/yosys_internals/formats/overview.rst deleted file mode 100644 index cbf5369bc..000000000 --- a/docs/source/yosys_internals/formats/overview.rst +++ /dev/null @@ -1,53 +0,0 @@ -Format overview -=============== - -Yosys uses two different internal formats. The first is used to store an -abstract syntax tree (AST) of a Verilog input file. This format is simply called -AST and is generated by the Verilog Frontend. This data structure is consumed by -a subsystem called AST Frontend [1]_. This AST Frontend then generates a design -in Yosys' main internal format, the -Register-Transfer-Level-Intermediate-Language (RTLIL) representation. It does -that by first performing a number of simplifications within the AST -representation and then generating RTLIL from the simplified AST data structure. - -The RTLIL representation is used by all passes as input and outputs. This has -the following advantages over using different representational formats between -different passes: - -- The passes can be rearranged in a different order and passes can be removed - or inserted. - -- Passes can simply pass-thru the parts of the design they don't change without - the need to convert between formats. In fact Yosys passes output the same - data structure they received as input and performs all changes in place. - -- All passes use the same interface, thus reducing the effort required to - understand a pass when reading the Yosys source code, e.g. when adding - additional features. - -The RTLIL representation is basically a netlist representation with the -following additional features: - -- An internal cell library with fixed-function cells to represent RTL datapath - and register cells as well as logical gate-level cells (single-bit gates and - registers). - -- Support for multi-bit values that can use individual bits from wires as well - as constant bits to represent coarse-grain netlists. - -- Support for basic behavioural constructs (if-then-else structures and - multi-case switches with a sensitivity list for updating the outputs). - -- Support for multi-port memories. - -The use of RTLIL also has the disadvantage of having a very powerful format -between all passes, even when doing gate-level synthesis where the more advanced -features are not needed. In order to reduce complexity for passes that operate -on a low-level representation, these passes check the features used in the input -RTLIL and fail to run when unsupported high-level constructs are used. In such -cases a pass that transforms the higher-level constructs to lower-level -constructs must be called from the synthesis script first. - -.. [1] - In Yosys the term pass is only used to refer to commands that operate on the - RTLIL data structure. \ No newline at end of file diff --git a/docs/source/yosys_internals/formats/rtlil_rep.rst b/docs/source/yosys_internals/formats/rtlil_rep.rst index 2737cd4bd..b0cbfe3a5 100644 --- a/docs/source/yosys_internals/formats/rtlil_rep.rst +++ b/docs/source/yosys_internals/formats/rtlil_rep.rst @@ -76,11 +76,10 @@ This has three advantages: - Second, the information about which identifiers were originally provided by the user is always available which can help guide some optimizations. For - example, :cmd:ref:`opt_clean` tries to preserve signals with a user-provided - name but doesn't hesitate to delete signals that have auto-generated names - when they just duplicate other signals. Note that this can be overridden - with the `-purge` option to also delete internal nets with user-provided - names. + example, `opt_clean` tries to preserve signals with a user-provided name but + doesn't hesitate to delete signals that have auto-generated names when they + just duplicate other signals. Note that this can be overridden with the + ``-purge`` option to also delete internal nets with user-provided names. - Third, the delicate job of finding suitable auto-generated public visible names is deferred to one central location. Internally auto-generated names @@ -204,8 +203,8 @@ A "signal" is everything that can be applied to a cell port. I.e. - | Concatenations of the above | 1em For example: ``{16'd1337, mywire[15:8]}`` -The ``RTLIL::SigSpec`` data type is used to represent signals. The ``RTLIL::Cell`` -object contains one ``RTLIL::SigSpec`` for each cell port. +The ``RTLIL::SigSpec`` data type is used to represent signals. The +``RTLIL::Cell`` object contains one ``RTLIL::SigSpec`` for each cell port. In addition, connections between wires are represented using a pair of ``RTLIL::SigSpec`` objects. Such pairs are needed in different locations. @@ -234,9 +233,9 @@ control logic of the behavioural code. Let's consider a simple example: q <= d; endmodule -In this example there is no data path and therefore the ``RTLIL::Module`` generated -by the frontend only contains a few ``RTLIL::Wire`` objects and an ``RTLIL::Process`` . -The ``RTLIL::Process`` in RTLIL syntax: +In this example there is no data path and therefore the ``RTLIL::Module`` +generated by the frontend only contains a few ``RTLIL::Wire`` objects and an +``RTLIL::Process``. The ``RTLIL::Process`` in RTLIL syntax: .. code:: RTLIL :number-lines: @@ -320,8 +319,8 @@ trees before further processing them. One of the first actions performed on a design in RTLIL representation in most synthesis scripts is identifying asynchronous resets. This is usually done using -the :cmd:ref:`proc_arst` pass. This pass transforms the above example to the -following ``RTLIL::Process``: +the `proc_arst` pass. This pass transforms the above example to the following +``RTLIL::Process``: .. code:: RTLIL :number-lines: @@ -340,9 +339,9 @@ following ``RTLIL::Process``: end This pass has transformed the outer ``RTLIL::SwitchRule`` into a modified -``RTLIL::SyncRule`` object for the ``\reset`` signal. Further processing converts the -``RTLIL::Process`` into e.g. a d-type flip-flop with asynchronous reset and a -multiplexer for the enable signal: +``RTLIL::SyncRule`` object for the ``\reset`` signal. Further processing +converts the ``RTLIL::Process`` into e.g. a d-type flip-flop with asynchronous +reset and a multiplexer for the enable signal: .. code:: RTLIL :number-lines: @@ -365,11 +364,11 @@ multiplexer for the enable signal: connect \Y $0\q[0:0] end -Different combinations of passes may yield different results. Note that -``$adff`` and ``$mux`` are internal cell types that still need to be mapped to -cell types from the target cell library. +Different combinations of passes may yield different results. Note that `$adff` +and `$mux` are internal cell types that still need to be mapped to cell types +from the target cell library. -Some passes refuse to operate on modules that still contain ``RTLIL::Process`` +Some passes refuse to operate on modules that still contain ``RTLIL::Process`` objects as the presence of these objects in a module increases the complexity. Therefore the passes to translate processes to a netlist of cells are usually called early in a synthesis script. The proc pass calls a series of other passes @@ -389,25 +388,25 @@ A memory object has the following properties: - The width of an addressable word - The size of the memory in number of words -All read accesses to the memory are transformed to ``$memrd`` cells and all -write accesses to ``$memwr`` cells by the language frontend. These cells consist -of independent read- and write-ports to the memory. Memory initialization is -transformed to ``$meminit`` cells by the language frontend. The ``\MEMID`` +All read accesses to the memory are transformed to `$memrd` cells and all write +accesses to `$memwr` cells by the language frontend. These cells consist of +independent read- and write-ports to the memory. Memory initialization is +transformed to `$meminit` cells by the language frontend. The ``\MEMID`` parameter on these cells is used to link them together and to the ``RTLIL::Memory`` object they belong to. The rationale behind using separate cells for the individual ports versus creating a large multiport memory cell right in the language frontend is that -the separate ``$memrd`` and ``$memwr`` cells can be consolidated using resource +the separate `$memrd` and `$memwr` cells can be consolidated using resource sharing. As resource sharing is a non-trivial optimization problem where different synthesis tasks can have different requirements it lends itself to do the optimisation in separate passes and merge the ``RTLIL::Memory`` objects and -``$memrd`` and ``$memwr`` cells to multiport memory blocks after resource -sharing is completed. +`$memrd` and `$memwr` cells to multiport memory blocks after resource sharing is +completed. The memory pass performs this conversion and can (depending on the options passed to it) transform the memories directly to d-type flip-flops and address -logic or yield multiport memory blocks (represented using ``$mem`` cells). +logic or yield multiport memory blocks (represented using `$mem` cells). See :ref:`sec:memcells` for details about the memory cell types. diff --git a/docs/source/yosys_internals/hashing.rst b/docs/source/yosys_internals/hashing.rst new file mode 100644 index 000000000..c6e22c0cf --- /dev/null +++ b/docs/source/yosys_internals/hashing.rst @@ -0,0 +1,166 @@ +Hashing and associative data structures in Yosys +------------------------------------------------ + +Container classes based on hashing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Yosys uses ``dict`` and ``pool`` as main container classes. +``dict`` is essentially a replacement for ``std::unordered_map`` +and ``pool`` is a replacement for ``std::unordered_set``. +The main characteristics are: + +* ``dict`` and ``pool`` are about 2x faster than the std containers + (though this claim hasn't been verified for over 10 years) + +* references to elements in a ``dict`` or ``pool`` are invalidated by + insert and remove operations (similar to ``std::vector`` on ``push_back()``). + +* some iterators are invalidated by ``erase()``. specifically, iterators + that have not passed the erased element yet are invalidated. (``erase()`` + itself returns valid iterator to the next element.) + +* no iterators are invalidated by ``insert()``. elements are inserted at + ``begin()``. i.e. only a new iterator that starts at ``begin()`` will see the + inserted elements. + +* the method ``.count(key, iterator)`` is like ``.count(key)`` but only + considers elements that can be reached via the iterator. + +* iterators can be compared. ``it1 < it2`` means that the position of ``t2`` + can be reached via ``t1`` but not vice versa. + +* the method ``.sort()`` can be used to sort the elements in the container + the container stays sorted until elements are added or removed. + +* ``dict`` and ``pool`` will have the same order of iteration across + all compilers, standard libraries and architectures. + +In addition to ``dict`` and ``pool`` there is also an ``idict`` that +creates a bijective map from ``K`` to the integers. For example: + +:: + + idict si; + log("%d\n", si("hello")); // will print 42 + log("%d\n", si("world")); // will print 43 + log("%d\n", si.at("world")); // will print 43 + log("%d\n", si.at("dummy")); // will throw exception + log("%s\n", si[42].c_str())); // will print hello + log("%s\n", si[43].c_str())); // will print world + log("%s\n", si[44].c_str())); // will throw exception + +It is not possible to remove elements from an idict. + +Finally ``mfp`` implements a merge-find set data structure (aka. disjoint-set +or union-find) over the type ``K`` ("mfp" = merge-find-promote). + +The hash function +~~~~~~~~~~~~~~~~~ + +The hash function generally used in Yosys is the XOR version of DJB2: + +:: + + state = ((state << 5) + state) ^ value + +This is an old-school hash designed to hash ASCII characters. Yosys doesn't hash +a lot of ASCII text, but it still happens to be a local optimum due to factors +described later. + +Hash function quality is multi-faceted and highly dependent on what is being +hashed. Yosys isn't concerned by any cryptographic qualities, instead the goal +is minimizing total hashing collision risk given the data patterns within Yosys. +In general, a good hash function typically folds values into a state accumulator +with a mathematical function that is fast to compute and has some beneficial +properties. One of these is the avalanche property, which demands that a small +change such as flipping a bit or incrementing by one in the input produces a +large, unpredictable change in the output. Additionally, the bit independence +criterion states that any pair of output bits should change independently when +any single input bit is inverted. These properties are important for avoiding +hash collision on data patterns like the hash of a sequence not colliding with +its permutation, not losing from the state the information added by hashing +preceding elements, etc. + +DJB2 lacks these properties. Instead, since Yosys hashes large numbers of data +structures composed of incrementing integer IDs, Yosys abuses the predictability +of DJB2 to get lower hash collisions, with regular nature of the hashes +surviving through the interaction with the "modulo prime" operations in the +associative data structures. For example, some most common objects in Yosys are +interned ``IdString``\ s of incrementing indices or ``SigBit``\ s with bit +offsets into wire (represented by its unique ``IdString`` name) as the typical +case. This is what makes DJB2 a local optimum. Additionally, the ADD version of +DJB2 (like above but with addition instead of XOR) is used to this end for some +types, abandoning the general pattern of folding values into a state value. + +Making a type hashable +~~~~~~~~~~~~~~~~~~~~~~ + +Let's first take a look at the external interface on a simplified level. +Generally, to get the hash for ``T obj``, you would call the utility function +``run_hash(const T& obj)``, corresponding to ``hash_ops::hash(obj)``, +the default implementation of which uses ``hash_ops::hash_into(Hasher(), obj)``. +``Hasher`` is the class actually implementing the hash function, hiding its +initialized internal state, and passing it out on ``hash_t yield()`` with +perhaps some finalization steps. + +``hash_ops`` is the star of the show. By default it pulls the ``Hasher h`` +through a ``Hasher T::hash_into(Hasher h)`` method. That's the method you have to +implement to make a record (class or struct) type easily hashable with Yosys +hashlib associative data structures. + +``hash_ops`` is specialized for built-in types like ``int`` or ``bool`` and +treats pointers the same as integers, so it doesn't dereference pointers. Since +many RTLIL data structures like ``RTLIL::Wire`` carry their own unique index +``Hasher::hash_t hashidx_;``, there are specializations for ``hash_ops`` +and others in ``kernel/hashlib.h`` that actually dereference the pointers and +call ``hash_into`` on the instances pointed to. + +``hash_ops`` is also specialized for simple compound types like +``std::pair`` by calling hash_into in sequence on its members. For flexible +size containers like ``std::vector`` the size of the container is hashed +first. That is also how implementing hashing for a custom record data type +should be - unless there is strong reason to do otherwise, call ``h.eat(m)`` on +the ``Hasher h`` you have received for each member in sequence and ``return +h;``. + +The ``hash_ops::hash(obj)`` method is not indended to be called when +context of implementing the hashing for a record or other compound type. +When writing it, you should connect it to ``hash_ops::hash_into(Hasher h)`` +as shown below. If you have a strong reason to do so, and you have +to create a special implementation for top-level hashing, look at how +``hash_ops::hash(...)`` is implemented in ``kernel/rtlil.h``. + +Porting plugins from the legacy interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Previously, the interface to implement hashing on custom types was just +``unsigned int T::hash() const``. This meant hashes for members were computed +independently and then ad-hoc combined with the hash function with some xorshift +operations thrown in to mix bits together somewhat. A plugin can stay compatible +with both versions prior and after the break by implementing both interfaces +based on the existance and value of `YS_HASHING_VERSION`. + +.. code-block:: cpp + :caption: Example hash compatibility wrapper + :name: hash_plugin_compat + + #ifndef YS_HASHING_VERSION + unsigned int T::hash() const { + return mkhash(a, b); + } + #elif YS_HASHING_VERSION == 1 + Hasher T::hash_into(Hasher h) const { + h.eat(a); + h.eat(b); + return h; + } + Hasher T::hash() const { + Hasher h; + h.eat(*this); + return h; + } + #else + #error "Unsupported hashing interface" + #endif + +Feel free to contact Yosys maintainers with related issues. diff --git a/docs/source/yosys_internals/index.rst b/docs/source/yosys_internals/index.rst index efd865623..3dd4224fa 100644 --- a/docs/source/yosys_internals/index.rst +++ b/docs/source/yosys_internals/index.rst @@ -38,3 +38,5 @@ as reference to implement a similar system in any language. formats/index extending_yosys/index techmap + verilog + hashing diff --git a/docs/source/yosys_internals/techmap.rst b/docs/source/yosys_internals/techmap.rst index 00fce26bd..21b09c903 100644 --- a/docs/source/yosys_internals/techmap.rst +++ b/docs/source/yosys_internals/techmap.rst @@ -1,9 +1,9 @@ Techmap by example ------------------ -As a quick recap, the :cmd:ref:`techmap` command replaces cells in the design -with implementations given as Verilog code (called "map files"). It can replace -Yosys' internal cell types (such as ``$or``) as well as user-defined cell types. +As a quick recap, the `techmap` command replaces cells in the design with +implementations given as Verilog code (called "map files"). It can replace +Yosys' internal cell types (such as `$or`) as well as user-defined cell types. - Verilog parameters are used extensively to customize the internal cell types. - Additional special parameters are used by techmap to communicate meta-data to @@ -87,15 +87,15 @@ Scripting in map modules - You can even call techmap recursively! - Example use-cases: - - Using always blocks in map module: call :cmd:ref:`proc` - - Perform expensive optimizations (such as :cmd:ref:`freduce`) on cells + - Using always blocks in map module: call `proc` + - Perform expensive optimizations (such as `freduce`) on cells where this is known to work well. - Interacting with custom commands. .. note:: PROTIP: - Commands such as :cmd:ref:`shell`, ``show -pause``, and :cmd:ref:`dump` can - be used in the ``_TECHMAP_DO_*`` scripts for debugging map modules. + Commands such as `shell`, ``show -pause``, and `dump` can be used in the + ``_TECHMAP_DO_*`` scripts for debugging map modules. Example: diff --git a/docs/source/yosys_internals/verilog.rst b/docs/source/yosys_internals/verilog.rst new file mode 100644 index 000000000..d67553aa9 --- /dev/null +++ b/docs/source/yosys_internals/verilog.rst @@ -0,0 +1,386 @@ +Notes on Verilog support in Yosys +================================= + +.. TODO:: how much of this is specific to the read_verilog and should be in :doc:`/yosys_internals/flow/verilog_frontend`? + +Unsupported Verilog-2005 Features +--------------------------------- + +The following Verilog-2005 features are not supported by +Yosys and there are currently no plans to add support +for them: + +- Non-synthesizable language features as defined in + IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002 + +- The ``tri``, ``triand`` and ``trior`` net types + +- The ``config`` and ``disable`` keywords and library map files + + +Verilog Attributes and non-standard features +-------------------------------------------- + +- The ``full_case`` attribute on case statements is supported (also the + non-standard ``// synopsys full_case`` directive) + +- The ``parallel_case`` attribute on case statements is supported (also the + non-standard ``// synopsys parallel_case`` directive) + +- The ``// synopsys translate_off`` and ``// synopsys translate_on`` directives + are also supported (but the use of ``` `ifdef .. `endif ``` is strongly + recommended instead). + +- The ``nomem2reg`` attribute on modules or arrays prohibits the automatic early + conversion of arrays to separate registers. This is potentially dangerous. + Usually the front-end has good reasons for converting an array to a list of + registers. Prohibiting this step will likely result in incorrect synthesis + results. + +- The ``mem2reg`` attribute on modules or arrays forces the early conversion of + arrays to separate registers. + +- The ``nomeminit`` attribute on modules or arrays prohibits the creation of + initialized memories. This effectively puts ``mem2reg`` on all memories that + are written to in an ``initial`` block and are not ROMs. + +- The ``nolatches`` attribute on modules or always-blocks prohibits the + generation of logic-loops for latches. Instead all not explicitly assigned + values default to x-bits. This does not affect clocked storage elements such + as flip-flops. + +- The ``nosync`` attribute on registers prohibits the generation of a storage + element. The register itself will always have all bits set to 'x' (undefined). + The variable may only be used as blocking assigned temporary variable within + an always block. This is mostly used internally by Yosys to synthesize Verilog + functions and access arrays. + +- The ``nowrshmsk`` attribute on a register prohibits the generation of + shift-and-mask type circuits for writing to bit slices of that register. + +- The ``onehot`` attribute on wires mark them as one-hot state register. This is + used for example for memory port sharing and set by the fsm_map pass. + +- The ``blackbox`` attribute on modules is used to mark empty stub modules that + have the same ports as the real thing but do not contain information on the + internal configuration. This modules are only used by the synthesis passes to + identify input and output ports of cells. The Verilog backend also does not + output blackbox modules on default. `read_verilog`, unless called with + ``-noblackbox`` will automatically set the blackbox attribute on any empty + module it reads. + +- The ``noblackbox`` attribute set on an empty module prevents `read_verilog` + from automatically setting the blackbox attribute on the module. + +- The ``whitebox`` attribute on modules triggers the same behavior as + ``blackbox``, but is for whitebox modules, i.e. library modules that contain a + behavioral model of the cell type. + +- The ``lib_whitebox`` attribute overwrites ``whitebox`` when `read_verilog` is + run in ``-lib`` mode. Otherwise it's automatically removed. + +- The ``dynports`` attribute is used by the Verilog front-end to mark modules + that have ports with a width that depends on a parameter. + +- The ``hdlname`` attribute is used by some passes to document the original + (HDL) name of a module when renaming a module. It should contain a single + name, or, when describing a hierarchical name in a flattened design, multiple + names separated by a single space character. + +- The ``keep`` attribute on cells and wires is used to mark objects that should + never be removed by the optimizer. This is used for example for cells that + have hidden connections that are not part of the netlist, such as IO pads. + Setting the ``keep`` attribute on a module has the same effect as setting it + on all instances of the module. + +- The ``keep_hierarchy`` attribute on cells and modules keeps the `flatten` + command from flattening the indicated cells and modules. + +- The `gate_cost_equivalent` attribute on a module can be used to specify + the estimated cost of the module as a number of basic gate instances. See + the help message of command `keep_hierarchy` which interprets this + attribute. + +- The ``init`` attribute on wires is set by the frontend when a register is + initialized "FPGA-style" with ``reg foo = val``. It can be used during + synthesis to add the necessary reset logic. + +- The ``top`` attribute on a module marks this module as the top of the design + hierarchy. The `hierarchy` command sets this attribute when called with + ``-top``. Other commands, such as `flatten` and various backends use this + attribute to determine the top module. + +- The ``src`` attribute is set on cells and wires created by to the string + ``:`` by the HDL front-end and is then carried + through the synthesis. When entities are combined, a new \|-separated string + is created that contains all the strings from the original entities. + +- The ``defaultvalue`` attribute is used to store default values for module + inputs. The attribute is attached to the input wire by the HDL front-end when + the input is declared with a default value. + +- The ``parameter`` and ``localparam`` attributes are used to mark wires that + represent module parameters or localparams (when the HDL front-end is run in + ``-pwires`` mode). + +- Wires marked with the ``hierconn`` attribute are connected to wires with the + same name (format ``cell_name.identifier``) when they are imported from + sub-modules by `flatten`. + +- The ``clkbuf_driver`` attribute can be set on an output port of a blackbox + module to mark it as a clock buffer output, and thus prevent `clkbufmap` from + inserting another clock buffer on a net driven by such output. + +- The ``clkbuf_sink`` attribute can be set on an input port of a module to + request clock buffer insertion by the `clkbufmap` pass. + +- The ``clkbuf_inv`` attribute can be set on an output port of a module with the + value set to the name of an input port of that module. When the `clkbufmap` + would otherwise insert a clock buffer on this output, it will instead try + inserting the clock buffer on the input port (this is used to implement clock + inverter cells that clock buffer insertion will "see through"). + +- The ``clkbuf_inhibit`` is the default attribute to set on a wire to prevent + automatic clock buffer insertion by `clkbufmap`. This behaviour can be + overridden by providing a custom selection to `clkbufmap`. + +- The ``invertible_pin`` attribute can be set on a port to mark it as invertible + via a cell parameter. The name of the inversion parameter is specified as the + value of this attribute. The value of the inversion parameter must be of the + same width as the port, with 1 indicating an inverted bit and 0 indicating a + non-inverted bit. + +- The ``iopad_external_pin`` attribute on a blackbox module's port marks it as + the external-facing pin of an I/O pad, and prevents `iopadmap` from inserting + another pad cell on it. + +- The module attribute ``abc9_lut`` is an integer attribute indicating to `abc9` + that this module describes a LUT with an area cost of this value, and + propagation delays described using ``specify`` statements. + +- The module attribute ``abc9_box`` is a boolean specifying a black/white-box + definition, with propagation delays described using ``specify`` statements, + for use by `abc9`. + +- The port attribute ``abc9_carry`` marks the carry-in (if an input port) and + carry-out (if output port) ports of a box. This information is necessary for + `abc9` to preserve the integrity of carry-chains. Specifying this attribute + onto a bus port will affect only its most significant bit. + +- The module attribute ``abc9_flop`` is a boolean marking the module as a + flip-flop. This allows `abc9` to analyse its contents in order to perform + sequential synthesis. + +- The frontend sets attributes ``always_comb``, ``always_latch`` and + ``always_ff`` on processes derived from SystemVerilog style always blocks + according to the type of the always. These are checked for correctness in + ``proc_dlatch``. + +- The cell attribute ``wildcard_port_conns`` represents wildcard port + connections (SystemVerilog ``.*``). These are resolved to concrete connections + to matching wires in `hierarchy`. + +- In addition to the ``(* ... *)`` attribute syntax, Yosys supports the + non-standard ``{* ... *}`` attribute syntax to set default attributes for + everything that comes after the ``{* ... *}`` statement. (Reset by adding an + empty ``{* *}`` statement.) + +- In module parameter and port declarations, and cell port and parameter lists, + a trailing comma is ignored. This simplifies writing Verilog code generators a + bit in some cases. + +- Modules can be declared with ``module mod_name(...);`` (with three dots + instead of a list of module ports). With this syntax it is sufficient to + simply declare a module port as 'input' or 'output' in the module body. + +- When defining a macro with ``\`define``, all text between triple double quotes + is interpreted as macro body, even if it contains unescaped newlines. The + triple double quotes are removed from the macro body. For example: + +.. code-block:: verilog + + `define MY_MACRO(a, b) """ + assign a = 23; + assign b = 42; + """ + +- The attribute ``via_celltype`` can be used to implement a Verilog task or + function by instantiating the specified cell type. The value is the name of + the cell type to use. For functions the name of the output port can be + specified by appending it to the cell type separated by a whitespace. The body + of the task or function is unused in this case and can be used to specify a + behavioral model of the cell type for simulation. For example: + +.. code-block:: verilog + + module my_add3(A, B, C, Y); + parameter WIDTH = 8; + input [WIDTH-1:0] A, B, C; + output [WIDTH-1:0] Y; + ... + endmodule + + module top; + ... + (* via_celltype = "my_add3 Y" *) + (* via_celltype_defparam_WIDTH = 32 *) + function [31:0] add3; + input [31:0] A, B, C; + begin + add3 = A + B + C; + end + endfunction + ... + endmodule + +- The ``wiretype`` attribute is added by the verilog parser for wires of a + typedef'd type to indicate the type identifier. + +- Various ``enum_value_{value}`` attributes are added to wires of an enumerated + type to give a map of possible enum items to their values. + +- The ``enum_base_type`` attribute is added to enum items to indicate which enum + they belong to (enums -- anonymous and otherwise -- are automatically named + with an auto-incrementing counter). Note that enums are currently not strongly + typed. + +- A limited subset of DPI-C functions is supported. The plugin mechanism (see + ``help plugin``) can be used to load .so files with implementations of DPI-C + routines. As a non-standard extension it is possible to specify a plugin alias + using the ``:`` syntax. For example: + +.. code-block:: verilog + + module dpitest; + import "DPI-C" function foo:round = real my_round (real); + parameter real r = my_round(12.345); + endmodule + +.. code-block:: + + $ yosys -p 'plugin -a foo -i /lib/libm.so; read_verilog dpitest.v' + +- Sized constants (the syntax ``'s?[bodh]``) support constant + expressions as ````. If the expression is not a simple identifier, it + must be put in parentheses. Examples: ``WIDTH'd42``, ``(4+2)'b101010`` + +- The system tasks ``$finish``, ``$stop`` and ``$display`` are supported in + initial blocks in an unconditional context (only if/case statements on + expressions over parameters and constant values are allowed). The intended use + for this is synthesis-time DRC. + +- There is limited support for converting ``specify`` .. ``endspecify`` + statements to special ``$specify2``, ``$specify3``, and ``$specrule`` cells, + for use in blackboxes and whiteboxes. Use ``read_verilog -specify`` to enable + this functionality. (By default these blocks are ignored.) + +- The ``reprocess_after`` internal attribute is used by the Verilog frontend to + mark cells with bindings which might depend on the specified instantiated + module. Modules with such cells will be reprocessed during the `hierarchy` + pass once the referenced module definition(s) become available. + +- The ``smtlib2_module`` attribute can be set on a blackbox module to specify a + formal model directly using SMT-LIB 2. For such a module, the + ``smtlib2_comb_expr`` attribute can be used on output ports to define their + value using an SMT-LIB 2 expression. For example: + +.. code-block:: verilog + + (* blackbox *) + (* smtlib2_module *) + module submod(a, b); + input [7:0] a; + (* smtlib2_comb_expr = "(bvnot a)" *) + output [7:0] b; + endmodule + +Non-standard or SystemVerilog features for formal verification +-------------------------------------------------------------- + +- Support for ``assert``, ``assume``, ``restrict``, and ``cover`` is enabled + when `read_verilog` is called with ``-formal``. + +- The system task ``$initstate`` evaluates to 1 in the initial state and to 0 + otherwise. + +- The system function ``$anyconst`` evaluates to any constant value. This is + equivalent to declaring a reg as ``rand const``, but also works outside of + checkers. (Yosys also supports ``rand const`` outside checkers.) + +- The system function ``$anyseq`` evaluates to any value, possibly a different + value in each cycle. This is equivalent to declaring a reg as ``rand``, but + also works outside of checkers. (Yosys also supports ``rand`` variables + outside checkers.) + +- The system functions ``$allconst`` and ``$allseq`` can be used to construct + formal exist-forall problems. Assumptions only hold if the trace satisfies the + assumption for all ``$allconst/$allseq`` values. For assertions and cover + statements it is sufficient if just one ``$allconst/$allseq`` value triggers + the property (similar to ``$anyconst/$anyseq``). + +- Wires/registers declared using the ``anyconst/anyseq/allconst/allseq`` + attribute (for example ``(* anyconst *) reg [7:0] foobar;``) will behave as if + driven by a ``$anyconst/$anyseq/$allconst/$allseq`` function. + +- The SystemVerilog tasks ``$past``, ``$stable``, ``$rose`` and ``$fell`` are + supported in any clocked block. + +- The syntax ``@($global_clock)`` can be used to create FFs that have no + explicit clock input (``$ff`` cells). The same can be achieved by using + ``@(posedge )`` or ``@(negedge )`` when ```` is + marked with the ``(* gclk *)`` Verilog attribute. + + +Supported features from SystemVerilog +------------------------------------- + +When `read_verilog` is called with ``-sv``, it accepts some language features +from SystemVerilog: + +- The ``assert`` statement from SystemVerilog is supported in its most basic + form. In module context: ``assert property ();`` and within an + always block: ``assert();``. It is transformed to an ``$assert`` + cell. + +- The ``assume``, ``restrict``, and ``cover`` statements from SystemVerilog are + also supported. The same limitations as with the ``assert`` statement apply. + +- The keywords ``always_comb``, ``always_ff`` and ``always_latch``, ``logic`` + and ``bit`` are supported. + +- Declaring free variables with ``rand`` and ``rand const`` is supported. + +- Checkers without a port list that do not need to be instantiated (but instead + behave like a named block) are supported. + +- SystemVerilog packages are supported. Once a SystemVerilog file is read into a + design with `read_verilog`, all its packages are available to SystemVerilog + files being read into the same design afterwards. + +- typedefs are supported (including inside packages) + - type casts are currently not supported + +- enums are supported (including inside packages) + - but are currently not strongly typed + +- packed structs and unions are supported + - arrays of packed structs/unions are currently not supported + - structure literals are currently not supported + +- multidimensional arrays are supported + - array assignment of unpacked arrays is currently not supported + - array literals are currently not supported + +- SystemVerilog interfaces (SVIs) are supported. Modports for specifying whether + ports are inputs or outputs are supported. + +- Assignments within expressions are supported. + +- The ``unique``, ``unique0``, and ``priority`` SystemVerilog keywords are + supported on ``if`` and ``case`` conditionals. (The Verilog frontend + will process conditionals using these keywords by annotating their + representation with the appropriate ``full_case`` and/or ``parallel_case`` + attributes, which are described above.) + +- SystemVerilog string literals are supported (triple-quoted strings and + escape sequences such as line continuations and hex escapes). diff --git a/docs/util/YoscryptLexer.py b/docs/util/YoscryptLexer.py deleted file mode 100644 index 8cb31c81a..000000000 --- a/docs/util/YoscryptLexer.py +++ /dev/null @@ -1,73 +0,0 @@ -from pygments.lexer import RegexLexer, bygroups, include -from pygments.token import (Comment, Error, Keyword, Name, Number, Operator, - String, Whitespace) - -__all__ = ['YoscryptLexer'] - -class YoscryptLexer(RegexLexer): - name = 'Yosys Script' - aliases = ['yoscrypt'] - filenames = ['*.ys'] - - - - tokens = { - 'common': [ - (r'\s+', Whitespace), - (r'#.*', Comment.Single), - (r'"', String, 'string'), - (r'(\d+)(\')([bdho]? ?\w+)', bygroups(Number, Operator, Number)), - (r'(\d+\.\d+)', Number.Float), - (r'(\d+)', Number), - (r'(\$[A-Za-z_0-9]*)', Name.Builtin), - (r'([A-Za-z_][A-Za-z_0-9\.\\/:-]*)', Name), - (r'(\[)(-\S*)(\])', # optional command - bygroups(Operator, Name.Attribute, Operator)), - (r'([\[<]\w*[\]>])', Name), # arguments - (r'[\{\}\|=\[\],]', Operator), - (r'.', Comment), - ], - 'root': [ - (r'([A-Za-z_][A-Za-z_0-9]*)', Keyword, 'command'), - (r'(-[A-Za-z_][A-Za-z_0-9]*)', Name.Attribute, 'command'), # shortcut for options - include('common'), - ], - 'command': [ - (r'(-[A-Za-z_][A-Za-z_0-9]*)', Name.Attribute), - (r'\+/[^\s]+', Name.Class), - (r'$', Whitespace, '#pop'), - (r';(?=\s)', Operator, '#pop'), - (r';{2,3}(?=\s)', Name.Class, '#pop'), - (r';{1,3}', Error, '#pop'), - (r'([ANwismctparn]:)', Keyword.Type, 'pattern'), - (r'@', Keyword.Type), - (r'%(x|ci|co)e?', Keyword.Type, 'expansion'), - (r'%[%nuidDcasmMCR]?', Keyword.Type), - (r'/', Operator), - include('common'), - ], - 'pattern': [ - (r'<<', Name), # Not an operator - (r'(=|<|<=|>|>=)', Operator), - (r':', Keyword.Type), - (r'$', Whitespace, '#pop:2'), - (r'\s+', Whitespace, '#pop'), - include('common'), - ], - 'expansion': [ - (r'$', Name.Class, '#pop:2'), - (r';(?=\s)', Operator, '#pop:2'), - (r';{2,3}(?=\s)', Name.Class, '#pop:2'), - (r'\s', Whitespace, '#pop'), - (r'[0-9\*]{1,3}', Number), - (r'[:+-,\[\]]', Operator), - include('common'), - ], - 'string': [ - (r'"', String, '#pop'), - (r'\\([\\abfnrtv"\']|x[a-fA-F0-9]{2,4}|[0-7]{1,3})', String.Escape), - (r'[^\\"\n]+', String), # all other characters - (r'(\\)(\n)', bygroups(String.Escape, Whitespace)), # line continuation - (r'\\', String), # stray backslash - ] - } diff --git a/docs/util/cellref.py b/docs/util/cellref.py new file mode 100644 index 000000000..58e65c2ea --- /dev/null +++ b/docs/util/cellref.py @@ -0,0 +1,415 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +from dataclasses import dataclass +import json +from pathlib import Path, PosixPath, WindowsPath +import re + +from typing import Any +from sphinx.application import Sphinx +from sphinx.ext import autodoc +from sphinx.ext.autodoc import Documenter +from sphinx.util import logging + +logger = logging.getLogger(__name__) + +# cell signature +cell_ext_sig_re = re.compile( + r'''^ ([^:\s]+::)? # optional group or file name + ([\w$._]+?) # module name + (?:\.([\w_]+))? # optional: thing name + (::[\w_]+)? # attribute + \s* $ # and nothing more + ''', re.VERBOSE) + +@dataclass +class YosysCell: + name: str + title: str + ports: str + source: str + desc: str + code: str + inputs: list[str] + outputs: list[str] + properties: list[str] + +class YosysCellGroupDocumenter(Documenter): + objtype = 'cellgroup' + priority = 10 + object: tuple[str, list[str]] + lib_key = 'groups' + + option_spec = { + 'caption': autodoc.annotation_option, + 'members': autodoc.members_option, + 'source': autodoc.bool_option, + 'linenos': autodoc.bool_option, + } + + __cell_lib: dict[str, list[str] | dict[str]] | None = None + @property + def cell_lib(self) -> dict[str, list[str] | dict[str]]: + if not self.__cell_lib: + self.__cell_lib = {} + cells_obj: dict[str, dict[str, list[str] | dict[str]]] + try: + with open(self.config.cells_json, "r") as f: + cells_obj = json.loads(f.read()) + except FileNotFoundError: + logger.warning( + f"unable to find cell lib at {self.config.cells_json}", + type = 'cellref', + subtype = 'cell_lib' + ) + else: + for (name, obj) in cells_obj.get(self.lib_key, {}).items(): + self.__cell_lib[name] = obj + return self.__cell_lib + + @classmethod + def can_document_member( + cls, + member: Any, + membername: str, + isattr: bool, + parent: Any + ) -> bool: + return False + + def parse_name(self) -> bool: + if not self.options.caption: + self.content_indent = '' + self.fullname = self.modname = self.name + return True + + def import_object(self, raiseerror: bool = False) -> bool: + # get cell + try: + self.object = (self.modname, self.cell_lib[self.modname]) + except KeyError: + if raiseerror: + raise + return False + + self.real_modname = self.modname + return True + + def get_sourcename(self) -> str: + return self.env.doc2path(self.env.docname) + + def format_name(self) -> str: + return self.options.caption or '' + + def format_signature(self, **kwargs: Any) -> str: + return self.modname + + def add_directive_header(self, sig: str) -> None: + domain = getattr(self, 'domain', 'cell') + directive = getattr(self, 'directivetype', 'group') + name = self.format_name() + sourcename = self.get_sourcename() + cell_list = self.object + + # cell definition + self.add_line(f'.. {domain}:{directive}:: {sig}', sourcename) + self.add_line(f' :caption: {name}', sourcename) + + if self.options.noindex: + self.add_line(' :noindex:', sourcename) + + def add_content(self, more_content: Any | None) -> None: + # groups have no native content + # add additional content (e.g. from document), if present + if more_content: + for line, src in zip(more_content.data, more_content.items): + self.add_line(line, src[0], src[1]) + + def filter_members( + self, + members: list[tuple[str, Any]], + want_all: bool + ) -> list[tuple[str, Any, bool]]: + return [(x[0], x[1], False) for x in members] + + def get_object_members( + self, + want_all: bool + ) -> tuple[bool, list[tuple[str, Any]]]: + ret: list[tuple[str, str]] = [] + + if want_all: + for member in self.object[1]: + ret.append((member, self.modname)) + else: + memberlist = self.options.members or [] + for name in memberlist: + if name in self.object: + ret.append((name, self.modname)) + else: + logger.warning(('unknown module mentioned in :members: option: ' + f'group {self.modname}, module {name}'), + type='cellref') + + return False, ret + + def document_members(self, all_members: bool = False) -> None: + want_all = (all_members or + self.options.inherited_members or + self.options.members is autodoc.ALL) + # find out which members are documentable + members_check_module, members = self.get_object_members(want_all) + + # document non-skipped members + memberdocumenters: list[tuple[Documenter, bool]] = [] + for (mname, member, isattr) in self.filter_members(members, want_all): + classes = [cls for cls in self.documenters.values() + if cls.can_document_member(member, mname, isattr, self)] + if not classes: + # don't know how to document this member + continue + # prefer the documenter with the highest priority + classes.sort(key=lambda cls: cls.priority) + # give explicitly separated module name, so that members + # of inner classes can be documented + full_mname = self.format_signature() + '::' + mname + documenter = classes[-1](self.directive, full_mname, self.indent) + memberdocumenters.append((documenter, isattr)) + + member_order = self.options.member_order or self.config.autodoc_member_order + memberdocumenters = self.sort_members(memberdocumenters, member_order) + + for documenter, isattr in memberdocumenters: + documenter.generate( + all_members=True, real_modname=self.real_modname, + check_module=members_check_module and not isattr) + + def generate( + self, + more_content: Any | None = None, + real_modname: str | None = None, + check_module: bool = False, + all_members: bool = False + ) -> None: + if not self.parse_name(): + # need a cell lib to import from + logger.warning( + f"don't know which cell lib to import for autodocumenting {self.name}", + type = 'cellref' + ) + return + + if not self.import_object(): + logger.warning( + f"unable to load {self.name}", + type = 'cellref' + ) + return + + # check __module__ of object (for members not given explicitly) + # if check_module: + # if not self.check_module(): + # return + + sourcename = self.get_sourcename() + self.add_line('', sourcename) + + # format the object's signature, if any + try: + sig = self.format_signature() + except Exception as exc: + logger.warning(('error while formatting signature for %s: %s'), + self.fullname, exc, type='cellref') + return + + # generate the directive header and options, if applicable + self.add_directive_header(sig) + self.add_line('', sourcename) + + # e.g. the module directive doesn't have content + self.indent += self.content_indent + + # add all content (from docstrings, attribute docs etc.) + self.add_content(more_content) + + # document members, if possible + self.document_members(all_members) + +class YosysCellDocumenter(YosysCellGroupDocumenter): + objtype = 'cell' + priority = 15 + object: YosysCell + lib_key = 'cells' + + @classmethod + def can_document_member( + cls, + member: Any, + membername: str, + isattr: bool, + parent: Any + ) -> bool: + if membername == "__source": + return False + if not membername.startswith('$'): + return False + return isinstance(parent, YosysCellGroupDocumenter) + + def parse_name(self) -> bool: + try: + matched = cell_ext_sig_re.match(self.name) + group, modname, thing, attribute = matched.groups() + except AttributeError: + logger.warning(('invalid signature for auto%s (%r)') % (self.objtype, self.name), + type='cellref') + return False + + self.modname = modname + self.groupname = group or '' + self.attribute = attribute or '' + self.fullname = ((self.modname) + (thing or '')) + + return True + + def import_object(self, raiseerror: bool = False) -> bool: + if super().import_object(raiseerror): + self.object = YosysCell(self.modname, **self.object[1]) + return True + return False + + def get_sourcename(self) -> str: + return self.object.source.split(":")[0] + + def format_name(self) -> str: + return self.object.name + + def format_signature(self, **kwargs: Any) -> str: + return self.groupname + self.fullname + self.attribute + + def add_directive_header(self, sig: str) -> None: + domain = getattr(self, 'domain', self.objtype) + directive = getattr(self, 'directivetype', 'def') + name = self.format_name() + sourcename = self.get_sourcename() + cell = self.object + + # cell definition + self.add_line(f'.. {domain}:{directive}:: {sig}', sourcename) + + # options + opt_attrs = ["title", "properties", ] + for attr in opt_attrs: + val = getattr(cell, attr, None) + if isinstance(val, list): + val = ' '.join(val) + if val: + self.add_line(f' :{attr}: {val}', sourcename) + + self.add_line('\n', sourcename) + + if self.options.noindex: + self.add_line(' :noindex:', sourcename) + + def add_content(self, more_content: Any | None) -> None: + # set sourcename and add content from attribute documentation + sourcename = self.get_sourcename() + startline = int(self.object.source.split(":")[1]) + + for i, line in enumerate(self.object.desc.splitlines(), startline): + self.add_line(line, sourcename, i) + + # add additional content (e.g. from document), if present + if more_content: + for line, src in zip(more_content.data, more_content.items): + self.add_line(line, src[0], src[1]) + + # fields + self.add_line('\n', sourcename) + field_attrs = ["properties", ] + for field in field_attrs: + attr = getattr(self.object, field, []) + for val in attr: + self.add_line(f':{field} {val}:', sourcename) + + def get_object_members( + self, + want_all: bool + ) -> tuple[bool, list[tuple[str, Any]]]: + ret: list[tuple[str, str]] = [] + + if self.options.source: + ret.append(('__source', self.real_modname)) + + return False, ret + +class YosysCellSourceDocumenter(YosysCellDocumenter): + objtype = 'cellsource' + priority = 20 + + @classmethod + def can_document_member( + cls, + member: Any, + membername: str, + isattr: bool, + parent: Any + ) -> bool: + if membername != "__source": + return False + if isinstance(parent, YosysCellDocumenter): + return True + return False + + def add_directive_header(self, sig: str) -> None: + domain = getattr(self, 'domain', 'cell') + directive = getattr(self, 'directivetype', 'source') + name = self.format_name() + sourcename = self.get_sourcename() + cell = self.object + + # cell definition + self.add_line(f'.. {domain}:{directive}:: {sig}', sourcename) + + if self.options.linenos: + self.add_line(f' :source: {cell.source.split(":")[0]}', sourcename) + else: + self.add_line(f' :source: {cell.source}', sourcename) + self.add_line(f' :language: verilog', sourcename) + + if self.options.linenos: + startline = int(self.object.source.split(":")[1]) + self.add_line(f' :lineno-start: {startline}', sourcename) + + if self.options.noindex: + self.add_line(' :noindex:', sourcename) + + def add_content(self, more_content: Any | None) -> None: + # set sourcename and add content from attribute documentation + sourcename = self.get_sourcename() + startline = int(self.object.source.split(":")[1]) + + for i, line in enumerate(self.object.code.splitlines(), startline-1): + self.add_line(line, sourcename, i) + + # add additional content (e.g. from document), if present + if more_content: + for line, src in zip(more_content.data, more_content.items): + self.add_line(line, src[0], src[1]) + + def get_object_members( + self, + want_all: bool + ) -> tuple[bool, list[tuple[str, Any]]]: + return False, [] + +def setup(app: Sphinx) -> dict[str, Any]: + app.add_config_value('cells_json', False, 'html', [Path, PosixPath, WindowsPath]) + app.setup_extension('sphinx.ext.autodoc') + app.add_autodocumenter(YosysCellDocumenter) + app.add_autodocumenter(YosysCellSourceDocumenter) + app.add_autodocumenter(YosysCellGroupDocumenter) + return { + 'version': '1', + 'parallel_read_safe': True, + } diff --git a/docs/util/cmdref.py b/docs/util/cmdref.py index ec146e231..a31b08e0d 100644 --- a/docs/util/cmdref.py +++ b/docs/util/cmdref.py @@ -1,72 +1,344 @@ # based on https://github.com/ofosos/sphinxrecipes/blob/master/sphinxrecipes/sphinxrecipes.py -# license: -# Copyright 2019 Mark Meyer -# -# Permission is hereby granted, free of charge, to any person obtaining -# a copy of this software and associated documentation files (the -# "Software"), to deal in the Software without restriction, including -# without limitation the rights to use, copy, modify, merge, publish, -# distribute, sublicense, and/or sell copies of the Software, and to -# permit persons to whom the Software is furnished to do so, subject to -# the following conditions: -# -# The above copyright notice and this permission notice shall be -# included in all copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE -# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION -# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION -# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -import docutils +from __future__ import annotations + +import re +from typing import cast + from docutils import nodes -import sphinx -from docutils.parsers import rst +from docutils.nodes import Node, Element, system_message from docutils.parsers.rst import directives +from docutils.parsers.rst.states import Inliner +from sphinx.application import Sphinx from sphinx.domains import Domain, Index from sphinx.domains.std import StandardDomain +from sphinx.environment import BuildEnvironment from sphinx.roles import XRefRole from sphinx.directives import ObjectDescription +from sphinx.directives.code import container_wrapper from sphinx.util.nodes import make_refnode +from sphinx.util.docfields import Field from sphinx import addnodes -class CommandNode(ObjectDescription): +class TocNode(ObjectDescription): + def add_target_and_index( + self, + name: str, + sig: str, + signode: addnodes.desc_signature + ) -> None: + idx = ".".join(name.split("::")) + signode['ids'].append(idx) + + def _object_hierarchy_parts(self, sig_node: addnodes.desc_signature) -> tuple[str, ...]: + if 'fullname' not in sig_node: + return () + + modname = sig_node.get('module') + fullname = sig_node['fullname'] + + if modname: + return (modname, *fullname.split('::')) + else: + return tuple(fullname.split('::')) + + def _toc_entry_name(self, sig_node: addnodes.desc_signature) -> str: + if not sig_node.get('_toc_parts'): + return '' + + config = self.env.app.config + objtype = sig_node.parent.get('objtype') + *parents, name = sig_node['_toc_parts'] + if config.toc_object_entries_show_parents == 'domain': + return sig_node.get('tocname', name) + if config.toc_object_entries_show_parents == 'hide': + return name + if config.toc_object_entries_show_parents == 'all': + return '.'.join(parents + [name]) + return '' + +class CommandNode(TocNode): """A custom node that describes a command.""" - + + name = 'cmd' required_arguments = 1 option_spec = { - 'title': directives.unchanged_required, + 'title': directives.unchanged, 'tags': directives.unchanged } def handle_signature(self, sig, signode: addnodes.desc_signature): + signode['fullname'] = sig signode += addnodes.desc_addname(text="yosys> help ") signode += addnodes.desc_name(text=sig) - return sig + return signode['fullname'] def add_target_and_index(self, name_cls, sig, signode): - signode['ids'].append('cmd' + '-' + sig) + idx = type(self).name + '-' + sig + signode['ids'].append(idx) if 'noindex' not in self.options: - name = "{}.{}.{}".format('cmd', type(self).__name__, sig) - tagmap = self.env.domaindata['cmd']['obj2tag'] + name = "{}.{}.{}".format(self.name, type(self).__name__, sig) + tagmap = self.env.domaindata[type(self).name]['obj2tag'] tagmap[name] = list(self.options.get('tags', '').split(' ')) - title = self.options.get('title') - titlemap = self.env.domaindata['cmd']['obj2title'] + title = self.options.get('title', sig) + titlemap = self.env.domaindata[type(self).name]['obj2title'] titlemap[name] = title - objs = self.env.domaindata['cmd']['objects'] + objs = self.env.domaindata[type(self).name]['objects'] + # (name, sig, typ, docname, anchor, prio) objs.append((name, sig, - title, + type(self).name, self.env.docname, - 'cmd' + '-' + sig, + idx, 0)) +class PropNode(TocNode): + name = 'prop' + fieldname = 'props' + + def handle_signature(self, sig: str, signode: addnodes.desc_signature): + signode['fullname'] = sig + signode['tocname'] = tocname = sig.split('::')[-1] + signode += addnodes.desc_name(text=tocname) + return signode['fullname'] + + def add_target_and_index( + self, + name: str, + sig: str, + signode: addnodes.desc_signature + ) -> None: + idx = ".".join(name.split("::")) + signode['ids'].append(idx) + if 'noindex' not in self.options: + tocname: str = signode.get('tocname', name) + objs = self.env.domaindata[self.domain]['objects'] + # (name, sig, typ, docname, anchor, prio) + objs.append((name, + tocname, + type(self).name, + self.env.docname, + idx, + 1)) + +class CellGroupedField(Field): + """Custom version of GroupedField which doesn't require content.""" + is_grouped = True + list_type = nodes.bullet_list + + def __init__(self, name: str, names: tuple[str, ...] = (), label: str = None, + rolename: str = None, can_collapse: bool = False) -> None: + super().__init__(name, names, label, True, rolename) + self.can_collapse = can_collapse + + def make_field(self, types: dict[str, list[Node]], domain: str, + items: tuple, env: BuildEnvironment = None, + inliner: Inliner = None, location: Node = None) -> nodes.field: + fieldname = nodes.field_name('', self.label) + listnode = self.list_type() + for fieldarg, content in items: + par = nodes.paragraph() + if fieldarg: + par.extend(self.make_xrefs(self.rolename, domain, + fieldarg, nodes.Text, + env=env, inliner=inliner, location=location)) + + if len(content) == 1 and ( + isinstance(content[0], nodes.Text) or + (isinstance(content[0], nodes.inline) and len(content[0]) == 1 and + isinstance(content[0][0], nodes.Text))): + par += nodes.Text(' -- ') + par += content + listnode += nodes.list_item('', par) + + if len(items) == 1 and self.can_collapse: + list_item = cast(nodes.list_item, listnode[0]) + fieldbody = nodes.field_body('', list_item[0]) + return nodes.field('', fieldname, fieldbody) + + fieldbody = nodes.field_body('', listnode) + return nodes.field('', fieldname, fieldbody) + +class CellNode(TocNode): + """A custom node that describes an internal cell.""" + + name = 'cell' + + option_spec = { + 'title': directives.unchanged, + 'ports': directives.unchanged, + 'properties': directives.unchanged, + } + + doc_field_types = [ + CellGroupedField('props', label='Properties', rolename='prop', + names=('properties', 'property', 'tag', 'tags'), + can_collapse=True), + ] + + def handle_signature(self, sig: str, signode: addnodes.desc_signature): + signode['fullname'] = sig + signode['tocname'] = tocname = sig.split('::')[-1] + signode += addnodes.desc_addname(text="yosys> help ") + signode += addnodes.desc_name(text=tocname) + return signode['fullname'] + + def add_target_and_index( + self, + name: str, + sig: str, + signode: addnodes.desc_signature + ) -> None: + idx = ".".join(name.split("::")) + signode['ids'].append(idx) + if 'noindex' not in self.options: + tocname: str = signode.get('tocname', name) + title: str = self.options.get('title', sig) + titlemap = self.env.domaindata[self.domain]['obj2title'] + titlemap[name] = title + props = self.options.get('properties', '') + if props: + propmap = self.env.domaindata[self.domain]['obj2prop'] + propmap[name] = props.split(' ') + objs = self.env.domaindata[self.domain]['objects'] + # (name, sig, typ, docname, anchor, prio) + objs.append((name, + tocname, + type(self).name, + self.env.docname, + idx, + 0)) + + def transform_content(self, contentnode: addnodes.desc_content) -> None: + # Add the cell title to the body + if 'title' in self.options: + titlenode = nodes.paragraph() + titlenode += nodes.strong() + titlenode[-1] += nodes.Text(self.options['title']) + contentnode.insert(0, titlenode) + +class CellSourceNode(TocNode): + """A custom code block for including cell source.""" + + name = 'cellsource' + + option_spec = { + "source": directives.unchanged_required, + "language": directives.unchanged_required, + 'lineno-start': int, + } + + def handle_signature( + self, + sig, + signode: addnodes.desc_signature + ) -> str: + language = self.options.get('language') + signode['fullname'] = sig + signode['tocname'] = f"{sig.split('::')[-2]} {language}" + signode += addnodes.desc_name(text="Simulation model") + signode += addnodes.desc_sig_space() + signode += addnodes.desc_addname(text=f'({language})') + return signode['fullname'] + + def run(self) -> list[Node]: + """Override run to parse content as a code block""" + if ':' in self.name: + self.domain, self.objtype = self.name.split(':', 1) + else: + self.domain, self.objtype = '', self.name + self.indexnode = addnodes.index(entries=[]) + + node = addnodes.desc() + node.document = self.state.document + source, line = self.get_source_info() + if line is not None: + line -= 1 + self.state.document.note_source(source, line) + node['domain'] = self.domain + # 'desctype' is a backwards compatible attribute + node['objtype'] = node['desctype'] = self.objtype + node['noindex'] = noindex = ('noindex' in self.options) + node['noindexentry'] = ('noindexentry' in self.options) + node['nocontentsentry'] = ('nocontentsentry' in self.options) + if self.domain: + node['classes'].append(self.domain) + node['classes'].append(node['objtype']) + + self.names = [] + signatures = self.get_signatures() + for sig in signatures: + # add a signature node for each signature in the current unit + # and add a reference target for it + signode = addnodes.desc_signature(sig, '') + self.set_source_info(signode) + node.append(signode) + try: + # name can also be a tuple, e.g. (classname, objname); + # this is strictly domain-specific (i.e. no assumptions may + # be made in this base class) + name = self.handle_signature(sig, signode) + except ValueError: + # signature parsing failed + signode.clear() + signode += addnodes.desc_name(sig, sig) + continue # we don't want an index entry here + finally: + # Private attributes for ToC generation. Will be modified or removed + # without notice. + if self.env.app.config.toc_object_entries: + signode['_toc_parts'] = self._object_hierarchy_parts(signode) + signode['_toc_name'] = self._toc_entry_name(signode) + else: + signode['_toc_parts'] = () + signode['_toc_name'] = '' + if name not in self.names: + self.names.append(name) + if not noindex: + # only add target and index entry if this is the first + # description of the object with this name in this desc block + self.add_target_and_index(name, sig, signode) + + # handle code + code = '\n'.join(self.content) + literal: Element = nodes.literal_block(code, code) + if 'lineno-start' in self.options: + literal['linenos'] = True + literal['highlight_args'] = { + 'linenostart': self.options['lineno-start'] + } + literal['classes'] += self.options.get('class', []) + literal['language'] = self.options.get('language') + literal = container_wrapper(self, literal, self.options.get('source')) + + return [self.indexnode, node, literal] + +class CellGroupNode(TocNode): + name = 'cellgroup' + + option_spec = { + 'caption': directives.unchanged, + } + + def add_target_and_index(self, name: str, sig: str, signode: addnodes.desc_signature) -> None: + if self.options.get('caption', ''): + super().add_target_and_index(name, sig, signode) + + def handle_signature( + self, + sig, + signode: addnodes.desc_signature + ) -> str: + signode['fullname'] = fullname = sig + caption = self.options.get("caption", fullname) + if caption: + signode['tocname'] = caption + signode += addnodes.desc_name(text=caption) + return fullname + class TagIndex(Index): - """A custom directive that creates an tag matrix.""" + """A custom directive that creates a tag matrix.""" name = 'tag' localname = 'Tag Index' @@ -107,7 +379,7 @@ class TagIndex(Index): in self.domain.get_objects()} tmap = {} - tags = self.domain.data['obj2tag'] + tags = self.domain.data[f'obj2{self.name}'] for name, tags in tags.items(): for tag in tags: tmap.setdefault(tag,[]) @@ -123,10 +395,9 @@ class TagIndex(Index): anchor, docname, '', typ )) - re = [(k, v) for k, v in sorted(content.items())] - - return (re, True) + ret = [(k, v) for k, v in sorted(content.items())] + return (ret, True) class CommandIndex(Index): name = 'cmd' @@ -164,23 +435,81 @@ class CommandIndex(Index): content = {} items = ((name, dispname, typ, docname, anchor) for name, dispname, typ, docname, anchor, prio - in self.domain.get_objects()) + in self.domain.get_objects() + if typ == self.name) items = sorted(items, key=lambda item: item[0]) for name, dispname, typ, docname, anchor in items: - lis = content.setdefault('Command', []) + lis = content.setdefault(self.shortname, []) lis.append(( dispname, 0, docname, anchor, '', '', typ )) - re = [(k, v) for k, v in sorted(content.items())] + ret = [(k, v) for k, v in sorted(content.items())] - return (re, True) + return (ret, True) +class CellIndex(CommandIndex): + name = 'cell' + localname = 'Internal cell reference' + shortname = 'Internal cell' + +class PropIndex(TagIndex): + """A custom directive that creates a properties matrix.""" + + name = 'prop' + localname = 'Property Index' + shortname = 'Prop' + fieldname = 'props' + + def generate(self, docnames=None): + content = {} + + cells = {name: (dispname, docname, anchor) + for name, dispname, typ, docname, anchor, _ + in self.domain.get_objects() + if typ == 'cell'} + props = {name: (dispname, docname, anchor) + for name, dispname, typ, docname, anchor, _ + in self.domain.get_objects() + if typ == 'prop'} + + tmap: dict[str, list[str]] = {} + tags: dict[str, list[str]] = self.domain.data[f'obj2{self.name}'] + for name, tags in tags.items(): + for tag in tags: + tmap.setdefault(tag,[]) + tmap[tag].append(name) + + for tag in sorted(tmap.keys()): + test = re.match(r'^(\w+[_-])', tag) + tag_prefix = test.group(1) + lis = content.setdefault(tag_prefix, []) + try: + dispname, docname, anchor = props[tag] + except KeyError: + dispname = tag + docname = anchor = '' + lis.append(( + dispname, 1, docname, + anchor, + '', '', docname or 'unavailable' + )) + objlis = tmap[tag] + for objname in sorted(objlis): + dispname, docname, anchor = cells[objname] + lis.append(( + dispname, 2, docname, + anchor, + '', '', docname + )) + ret = [(k, v) for k, v in sorted(content.items())] + + return (ret, True) class CommandDomain(Domain): name = 'cmd' - label = 'Command Sample' + label = 'Yosys commands' roles = { 'ref': XRefRole() @@ -203,7 +532,7 @@ class CommandDomain(Domain): def get_full_qualified_name(self, node): """Return full qualified name for a given node""" - return "{}.{}.{}".format('cmd', + return "{}.{}.{}".format(type(self).name, type(node).__name__, node.arguments[0]) @@ -229,18 +558,68 @@ class CommandDomain(Domain): else: print(f"Missing ref for {target} in {fromdocname} ") return None + +class CellDomain(CommandDomain): + name = 'cell' + label = 'Yosys internal cells' -def setup(app): + roles = CommandDomain.roles.copy() + roles.update({ + 'prop': XRefRole() + }) + + directives = { + 'def': CellNode, + 'defprop': PropNode, + 'source': CellSourceNode, + 'group': CellGroupNode, + } + + indices = { + CellIndex, + PropIndex + } + + initial_data = { + 'objects': [], # object list + 'obj2prop': {}, # name -> properties + 'obj2title': {}, # name -> title + } + + def get_objects(self): + for obj in self.data['objects']: + yield(obj) + +def autoref(name, rawtext: str, text: str, lineno, inliner: Inliner, + options=None, content=None): + role = 'cell:ref' if text[0] == '$' else 'cmd:ref' + if text.startswith("help ") and text.count(' ') == 1: + _, cmd = text.split(' ', 1) + text = f'{text} <{cmd}>' + return inliner.interpreted(rawtext, text, role, lineno) + +def setup(app: Sphinx): app.add_domain(CommandDomain) + app.add_domain(CellDomain) StandardDomain.initial_data['labels']['commandindex'] =\ ('cmd-cmd', '', 'Command Reference') StandardDomain.initial_data['labels']['tagindex'] =\ ('cmd-tag', '', 'Tag Index') + StandardDomain.initial_data['labels']['cellindex'] =\ + ('cell-cell', '', 'Internal cell reference') + StandardDomain.initial_data['labels']['propindex'] =\ + ('cell-prop', '', 'Property Index') StandardDomain.initial_data['anonlabels']['commandindex'] =\ ('cmd-cmd', '') StandardDomain.initial_data['anonlabels']['tagindex'] =\ ('cmd-tag', '') + StandardDomain.initial_data['anonlabels']['cellindex'] =\ + ('cell-cell', '') + StandardDomain.initial_data['anonlabels']['propindex'] =\ + ('cell-prop', '') + + app.add_role('autoref', autoref) - return {'version': '0.1'} + return {'version': '0.2'} diff --git a/examples/cxx-api/scopeinfo_example.cc b/examples/cxx-api/scopeinfo_example.cc index f163dff9e..0882ba804 100644 --- a/examples/cxx-api/scopeinfo_example.cc +++ b/examples/cxx-api/scopeinfo_example.cc @@ -90,7 +90,7 @@ struct ScopeinfoExamplePass : public Pass { // Shuffle wires so this example produces more interesting outputs std::sort(wires.begin(), wires.end(), [](Wire *a, Wire *b) { - return mkhash_xorshift(a->name.hash() * 0x2c9277b5) < mkhash_xorshift(b->name.hash() * 0x2c9277b5); + return mkhash_xorshift(run_hash(a->name) * 0x2c9277b5) < mkhash_xorshift(run_hash(b->name) * 0x2c9277b5); }); ModuleHdlnameIndex index(module); diff --git a/flake.nix b/flake.nix index 90fa5328c..19ba59f17 100644 --- a/flake.nix +++ b/flake.nix @@ -14,15 +14,15 @@ }; # TODO: don't override src when ./abc is empty # which happens when the command used is `nix build` and not `nix build ?submodules=1` - abc-verifier = pkgs.abc-verifier.overrideAttrs(x: y: {src = ./abc;}); + abc-verifier = pkgs.abc-verifier; yosys = pkgs.clangStdenv.mkDerivation { name = "yosys"; src = ./. ; - buildInputs = with pkgs; [ clang bison flex libffi tcl readline python3 llvmPackages.libcxxClang zlib git pkg-configUpstream llvmPackages.bintools ]; + buildInputs = with pkgs; [ clang bison flex libffi tcl readline python3 zlib git pkg-configUpstream llvmPackages.bintools ]; checkInputs = with pkgs; [ gtest ]; propagatedBuildInputs = [ abc-verifier ]; preConfigure = "make config-clang"; - checkTarget = "test"; + checkTarget = "unit-test"; installPhase = '' make install PREFIX=$out ABCEXTERNAL=yosys-abc ln -s ${abc-verifier}/bin/abc $out/bin/yosys-abc @@ -41,7 +41,7 @@ packages.default = yosys; defaultPackage = yosys; devShell = pkgs.mkShell { - buildInputs = with pkgs; [ clang llvmPackages.bintools bison flex libffi tcl readline python3 llvmPackages.libcxxClang zlib git gtest abc-verifier ]; + buildInputs = with pkgs; [ clang llvmPackages.bintools gcc bison flex libffi tcl readline python3 zlib git gtest abc-verifier verilog boost python3Packages.boost ]; }; } ); diff --git a/frontends/aiger/aigerparse.cc b/frontends/aiger/aigerparse.cc index 0178514e1..37ace27fd 100644 --- a/frontends/aiger/aigerparse.cc +++ b/frontends/aiger/aigerparse.cc @@ -448,7 +448,7 @@ void AigerReader::parse_xaiger() bool success = ce.eval(o); log_assert(success); log_assert(o.wire == nullptr); - lut_mask[gray] = o.data; + lut_mask.bits()[gray] = o.data; } RTLIL::Cell *output_cell = module->cell(stringf("$and$aiger%d$%d", aiger_autoidx, rootNodeID)); log_assert(output_cell); diff --git a/frontends/aiger2/Makefile.inc b/frontends/aiger2/Makefile.inc new file mode 100644 index 000000000..b4a9f6b89 --- /dev/null +++ b/frontends/aiger2/Makefile.inc @@ -0,0 +1,2 @@ + +OBJS += frontends/aiger2/xaiger.o diff --git a/frontends/aiger2/xaiger.cc b/frontends/aiger2/xaiger.cc new file mode 100644 index 000000000..616bec9e7 --- /dev/null +++ b/frontends/aiger2/xaiger.cc @@ -0,0 +1,469 @@ +/* + * yosys -- Yosys Open SYnthesis Suite + * + * Copyright (C) Martin Povišer + * + * Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + * + */ + +#include "kernel/register.h" + +USING_YOSYS_NAMESPACE +PRIVATE_NAMESPACE_BEGIN + +uint32_t read_be32(std::istream &f) { + return ((uint32_t) f.get() << 24) | + ((uint32_t) f.get() << 16) | + ((uint32_t) f.get() << 8) | (uint32_t) f.get(); +} + +IdString read_idstring(std::istream &f) +{ + std::string str; + std::getline(f, str, '\0'); + if (!f.good()) + log_error("failed to read string\n"); + return RTLIL::escape_id(str); +} + +struct Xaiger2Frontend : public Frontend { + Xaiger2Frontend() : Frontend("xaiger2", "(experimental) read XAIGER file") + { + experimental(); + } + + void help() override + { + // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| + log("\n"); + log(" read_xaiger2 -sc_mapping [options] \n"); + log("\n"); + log("Read a standard cell mapping from a XAIGER file into an existing module.\n"); + log("\n"); + log(" -module_name \n"); + log(" name of the target module\n"); + log("\n"); + log(" -map2 \n"); + log(" read file with symbol information\n"); + log("\n"); + } + + void read_sc_mapping(std::istream *&f, std::string filename, std::vector args, Design *design) + { + IdString module_name; + std::string map_filename; + + size_t argidx; + for (argidx = 2; argidx < args.size(); argidx++) { + std::string arg = args[argidx]; + if (arg == "-module_name" && argidx + 1 < args.size()) { + module_name = RTLIL::escape_id(args[++argidx]); + continue; + } + if (arg == "-map2" && argidx + 1 < args.size()) { + map_filename = args[++argidx]; + continue; + } + break; + } + extra_args(f, filename, args, argidx, true); + + if (map_filename.empty()) + log_error("A '-map2' argument required\n"); + if (module_name.empty()) + log_error("A '-module_name' argument required\n"); + + Module *module = design->module(module_name); + if (!module) + log_error("Module '%s' not found\n", log_id(module_name)); + + std::ifstream map_file; + map_file.open(map_filename); + if (!map_file) + log_error("Failed to open map file '%s'\n", map_filename.c_str()); + + unsigned int M, I, L, O, A; + std::string header; + if (!(*f >> header >> M >> I >> L >> O >> A) || header != "aig") + log_error("Bad header\n"); + std::string line; + std::getline(*f, line); + log_debug("M=%u I=%u L=%u O=%u A=%u\n", M, I, L, O, A); + + if (L != 0) + log_error("Latches unsupported\n"); + if (I + L + A != M) + log_error("Inconsistent header\n"); + + std::vector outputs; + for (int i = 0; i < (int) O; i++) { + int po; + *f >> po; + log_assert(f->get() == '\n'); + outputs.push_back(po); + } + + std::vector> boxes; + std::vector retained_boxes; + std::vector bits(2 + 2*M, RTLIL::Sm); + bits[0] = RTLIL::S0; + bits[1] = RTLIL::S1; + + std::string type; + while (map_file >> type) { + if (type == "pi") { + int pi_idx; + int woffset; + std::string name; + if (!(map_file >> pi_idx >> woffset >> name)) + log_error("Bad map file (1)\n"); + int lit = (2 * pi_idx) + 2; + if (lit < 0 || lit >= (int) bits.size()) + log_error("Bad map file (2)\n"); + Wire *w = module->wire(name); + if (!w || woffset < 0 || woffset >= w->width) + log_error("Map file references non-existent signal bit %s[%d]\n", + name.c_str(), woffset); + bits[lit] = SigBit(w, woffset); + } else if (type == "box") { + int box_seq; + std::string name; + if (!(map_file >> box_seq >> name)) + log_error("Bad map file (20)\n"); + if (box_seq < 0) + log_error("Bad map file (21)\n"); + + Cell *box = module->cell(RTLIL::escape_id(name)); + if (!box) + log_error("Map file references non-existent box %s\n", + name.c_str()); + + Module *def = design->module(box->type); + if (def && !box->parameters.empty()) { + // TODO: This is potentially costly even if a cached derivation exists + def = design->module(def->derive(design, box->parameters)); + log_assert(def); + } + + if (!def) + log_error("Bad map file (22)\n"); + + if (box_seq >= (int) boxes.size()) { + boxes.resize(box_seq + 1); + retained_boxes.resize(box_seq + 1); + } + boxes[box_seq] = std::make_pair(box, def); + } else { + std::string scratch; + std::getline(map_file, scratch); + } + } + + for (int i = 0; i < (int) A; i++) { + while (f->get() & 0x80 && !f->eof()); + while (f->get() & 0x80 && !f->eof()); + } + + if (f->get() != 'c') + log_error("Missing 'c' ahead of extensions\n"); + if (f->peek() == '\n') + f->get(); + auto extensions_start = f->tellg(); + + log_debug("reading 'h' (first pass)\n"); + for (int c = f->get(); c != EOF; c = f->get()) { + if (c == 'h') { + uint32_t len, ci_num, co_num, pi_num, po_num, no_boxes; + len = read_be32(*f); + read_be32(*f); + ci_num = read_be32(*f); + co_num = read_be32(*f); + pi_num = read_be32(*f); + po_num = read_be32(*f); + no_boxes = read_be32(*f); + + log_debug("len=%u ci_num=%u co_num=%u pi_num=%u po_nun=%u no_boxes=%u\n", + len, ci_num, co_num, pi_num, po_num, no_boxes); + + int ci_counter = 0; + for (uint32_t i = 0; i < no_boxes; i++) { + /* unused box_inputs = */ read_be32(*f); + YS_MAYBE_UNUSED auto box_outputs = read_be32(*f); + /* unused box_id = */ read_be32(*f); + auto box_seq = read_be32(*f); + + log_assert(box_seq < boxes.size()); + + auto [cell, def] = boxes[box_seq]; + log_assert(cell && def); + retained_boxes[box_seq] = true; + + int box_ci_idx = 0; + for (auto port_id : def->ports) { + Wire *port = def->wire(port_id); + if (port->port_output) { + if (!cell->hasPort(port_id) || cell->getPort(port_id).size() != port->width) + log_error("Malformed design (1)\n"); + + SigSpec &conn = cell->connections_[port_id]; + for (int j = 0; j < port->width; j++) { + if (conn[j].wire && conn[j].wire->port_output) + conn[j] = module->addWire(module->uniquify( + stringf("$box$%s$%s$%d", + cell->name.isPublic() ? cell->name.c_str() + 1 : cell->name.c_str(), + port_id.isPublic() ? port_id.c_str() + 1 : port_id.c_str(), + j))); + + bits[2*(pi_num + ci_counter + box_ci_idx++) + 2] = conn[j]; + } + } + } + + log_assert(box_ci_idx == (int) box_outputs); + ci_counter += box_ci_idx; + } + log_assert(pi_num + ci_counter == ci_num); + } else if (c == '\n') { + break; + } else if (c == 'c') { + break; + } else { + uint32_t len = read_be32(*f); + f->ignore(len); + log_debug(" section '%c' (%d): ignoring %d bytes\n", c, c, len); + } + } + + log_debug("reading 'M' (second pass)\n"); + + f->seekg(extensions_start); + bool read_mapping = false; + uint32_t no_cells, no_instances; + for (int c = f->get(); c != EOF; c = f->get()) { + if (c == 'M') { + uint32_t len = read_be32(*f); + read_mapping = true; + + no_cells = read_be32(*f); + no_instances = read_be32(*f); + + log_debug("M: len=%u no_cells=%u no_instances=%u\n", len, no_cells, no_instances); + + struct MappingCell { + RTLIL::IdString type; + RTLIL::IdString out; + std::vector ins; + }; + std::vector cells; + cells.resize(no_cells); + + for (unsigned i = 0; i < no_cells; ++i) { + auto &cell = cells[i]; + cell.type = read_idstring(*f); + cell.out = read_idstring(*f); + uint32_t nins = read_be32(*f); + for (uint32_t j = 0; j < nins; j++) + cell.ins.push_back(read_idstring(*f)); + log_debug("M: Cell %s (out %s, ins", log_id(cell.type), log_id(cell.out)); + for (auto in : cell.ins) + log_debug(" %s", log_id(in)); + log_debug(")\n"); + } + + for (unsigned i = 0; i < no_instances; ++i) { + uint32_t cell_id = read_be32(*f); + uint32_t out_lit = read_be32(*f); + + log_assert(out_lit < bits.size()); + log_assert(bits[out_lit] == RTLIL::Sm); + log_assert(cell_id < cells.size()); + auto &cell = cells[cell_id]; + Cell *instance = module->addCell(module->uniquify(stringf("$sc%d", out_lit)), cell.type); + auto out_w = module->addWire(module->uniquify(stringf("$lit%d", out_lit))); + instance->setPort(cell.out, out_w); + bits[out_lit] = out_w; + for (auto in : cell.ins) { + uint32_t in_lit = read_be32(*f); + log_assert(out_lit < bits.size()); + log_assert(bits[in_lit] != RTLIL::Sm); + instance->setPort(in, bits[in_lit]); + } + } + } else if (c == '\n') { + break; + } else if (c == 'c') { + break; + } else { + uint32_t len = read_be32(*f); + f->ignore(len); + log_debug(" section '%c' (%d): ignoring %d bytes\n", c, c, len); + } + } + + if (!read_mapping) + log_error("Missing mapping (no 'M' section)\n"); + + log("Read %d instances with cell library of size %d.\n", + no_instances, no_cells); + + f->seekg(extensions_start); + log_debug("reading 'h' (second pass)\n"); + int co_counter = 0; + for (int c = f->get(); c != EOF; c = f->get()) { + if (c == 'h') { + uint32_t len, ci_num, co_num, pi_num, po_num, no_boxes; + len = read_be32(*f); + read_be32(*f); + ci_num = read_be32(*f); + co_num = read_be32(*f); + pi_num = read_be32(*f); + po_num = read_be32(*f); + no_boxes = read_be32(*f); + + log_debug("len=%u ci_num=%u co_num=%u pi_num=%u po_nun=%u no_boxes=%u\n", + len, ci_num, co_num, pi_num, po_num, no_boxes); + + for (uint32_t i = 0; i < no_boxes; i++) { + YS_MAYBE_UNUSED auto box_inputs = read_be32(*f); + /* unused box_outputs = */ read_be32(*f); + /* unused box_id = */ read_be32(*f); + auto box_seq = read_be32(*f); + + log_assert(box_seq < boxes.size()); + + auto [cell, def] = boxes[box_seq]; + log_assert(cell && def); + + int box_co_idx = 0; + for (auto port_id : def->ports) { + Wire *port = def->wire(port_id); + SigSpec conn; + if (port->port_input) { + if (!cell->hasPort(port_id) || cell->getPort(port_id).size() != port->width) + log_error("Malformed design (2)\n"); + + SigSpec conn; + for (int j = 0; j < port->width; j++) { + log_assert(co_counter + box_co_idx < (int) outputs.size()); + int lit = outputs[co_counter + box_co_idx++]; + log_assert(lit >= 0 && lit < (int) bits.size()); + SigBit bit = bits[lit]; + if (bit == RTLIL::Sm) + log_error("Malformed mapping (1)\n"); + conn.append(bit); + } + cell->setPort(port_id, conn); + } + } + + log_assert(box_co_idx == (int) box_inputs); + co_counter += box_co_idx; + } + log_assert(po_num + co_counter == co_num); + } else if (c == '\n') { + break; + } else if (c == 'c') { + break; + } else { + uint32_t len = read_be32(*f); + f->ignore(len); + log_debug(" section '%c' (%d): ignoring %d bytes\n", c, c, len); + } + } + + while (true) { + std::string scratch; + std::getline(*f, scratch); + if (f->eof()) + break; + log_assert(!f->fail()); + log("input file: %s\n", scratch.c_str()); + } + + log_debug("co_counter=%d\n", co_counter); + + // TODO: seek without close/open + map_file.close(); + map_file.open(map_filename); + while (map_file >> type) { + if (type == "po") { + int po_idx; + int woffset; + std::string name; + if (!(map_file >> po_idx >> woffset >> name)) + log_error("Bad map file (3)\n"); + po_idx += co_counter; + if (po_idx < 0 || po_idx >= (int) outputs.size()) + log_error("Bad map file (4)\n"); + int lit = outputs[po_idx]; + if (lit < 0 || lit >= (int) bits.size()) + log_error("Bad map file (5)\n"); + if (bits[lit] == RTLIL::Sm) + log_error("Bad map file (6)\n"); + Wire *w = module->wire(name); + if (!w || woffset < 0 || woffset >= w->width) + log_error("Map file references non-existent signal bit %s[%d]\n", + name.c_str(), woffset); + module->connect(SigBit(w, woffset), bits[lit]); + } else if (type == "pseudopo") { + int po_idx; + int poffset; + std::string box_name; + std::string box_port; + if (!(map_file >> po_idx >> poffset >> box_name >> box_port)) + log_error("Bad map file (7)\n"); + po_idx += co_counter; + if (po_idx < 0 || po_idx >= (int) outputs.size()) + log_error("Bad map file (8)\n"); + int lit = outputs[po_idx]; + if (lit < 0 || lit >= (int) bits.size()) + log_error("Bad map file (9)\n"); + if (bits[lit] == RTLIL::Sm) + log_error("Bad map file (10)\n"); + Cell *cell = module->cell(box_name); + if (!cell || !cell->hasPort(box_port)) + log_error("Map file references non-existent box port %s/%s\n", + box_name.c_str(), box_port.c_str()); + SigSpec &port = cell->connections_[box_port]; + if (poffset < 0 || poffset >= port.size()) + log_error("Map file references non-existent box port bit %s/%s[%d]\n", + box_name.c_str(), box_port.c_str(), poffset); + port[poffset] = bits[lit]; + } else { + std::string scratch; + std::getline(map_file, scratch); + } + } + + int box_seq = 0; + for (auto [cell, def] : boxes) { + if (!retained_boxes[box_seq++]) + module->remove(cell); + } + } + + void execute(std::istream *&f, std::string filename, std::vector args, Design *design) override + { + log_header(design, "Executing XAIGER2 frontend.\n"); + + if (args.size() > 1 && args[1] == "-sc_mapping") { + read_sc_mapping(f, filename, args, design); + return; + } + + log_cmd_error("Mode '-sc_mapping' must be selected\n"); + } +} Xaiger2Frontend; + +PRIVATE_NAMESPACE_END diff --git a/frontends/ast/ast.cc b/frontends/ast/ast.cc index d21b8f02d..431f7b4f8 100644 --- a/frontends/ast/ast.cc +++ b/frontends/ast/ast.cc @@ -41,6 +41,8 @@ namespace AST { std::string current_filename; void (*set_line_num)(int) = NULL; int (*get_line_num)() = NULL; + unsigned long long astnodes = 0; + unsigned long long astnode_count() { return astnodes; } } // instantiate global variables (private API) @@ -204,6 +206,7 @@ AstNode::AstNode(AstNodeType type, AstNode *child1, AstNode *child2, AstNode *ch static unsigned int hashidx_count = 123456789; hashidx_count = mkhash_xorshift(hashidx_count); hashidx_ = hashidx_count; + astnodes++; this->type = type; filename = current_filename; @@ -292,6 +295,7 @@ void AstNode::delete_children() // AstNode destructor AstNode::~AstNode() { + astnodes--; delete_children(); } @@ -474,6 +478,10 @@ void AstNode::dumpVlog(FILE *f, std::string indent) const fprintf(f, ";\n"); break; + case AST_WIRETYPE: + fprintf(f, "%s", id2vl(str).c_str()); + break; + case AST_MEMORY: fprintf(f, "%s" "memory", indent.c_str()); if (is_signed) @@ -690,7 +698,17 @@ void AstNode::dumpVlog(FILE *f, std::string indent) const break; case AST_CAST_SIZE: - children[0]->dumpVlog(f, ""); + switch (children[0]->type) + { + case AST_WIRE: + if (children[0]->children.size() > 0) + children[0]->children[0]->dumpVlog(f, ""); + else + fprintf(f, "%d'", children[0]->range_left - children[0]->range_right + 1); + break; + default: + children[0]->dumpVlog(f, ""); + } fprintf(f, "'("); children[1]->dumpVlog(f, ""); fprintf(f, ")"); @@ -859,16 +877,25 @@ AstNode *AstNode::mkconst_str(const std::vector &v) // create an AST node for a constant (using a string as value) AstNode *AstNode::mkconst_str(const std::string &str) { - std::vector data; - data.reserve(str.size() * 8); - for (size_t i = 0; i < str.size(); i++) { - unsigned char ch = str[str.size() - i - 1]; - for (int j = 0; j < 8; j++) { - data.push_back((ch & 1) ? State::S1 : State::S0); - ch = ch >> 1; + AstNode *node; + + // LRM 1364-2005 5.2.3.3 The empty string literal ("") shall be considered + // equivalent to the ASCII NUL ("\0") + if (str.empty()) { + node = AstNode::mkconst_int(0, false, 8); + } else { + std::vector data; + data.reserve(str.size() * 8); + for (size_t i = 0; i < str.size(); i++) { + unsigned char ch = str[str.size() - i - 1]; + for (int j = 0; j < 8; j++) { + data.push_back((ch & 1) ? State::S1 : State::S0); + ch = ch >> 1; + } } + node = AstNode::mkconst_bits(data, false); } - AstNode *node = AstNode::mkconst_bits(data, false); + node->is_string = true; node->str = str; return node; @@ -904,7 +931,7 @@ bool AstNode::bits_only_01() const RTLIL::Const AstNode::bitsAsUnsizedConst(int width) { RTLIL::State extbit = bits.back(); - while (width > int(bits.size())) + while (width > GetSize(bits)) bits.push_back(extbit); return RTLIL::Const(bits); } @@ -912,13 +939,13 @@ RTLIL::Const AstNode::bitsAsUnsizedConst(int width) RTLIL::Const AstNode::bitsAsConst(int width, bool is_signed) { std::vector bits = this->bits; - if (width >= 0 && width < int(bits.size())) + if (width >= 0 && width < GetSize(bits)) bits.resize(width); - if (width >= 0 && width > int(bits.size())) { + if (width >= 0 && width > GetSize(bits)) { RTLIL::State extbit = RTLIL::State::S0; if ((is_signed || is_unsized) && !bits.empty()) extbit = bits.back(); - while (width > int(bits.size())) + while (width > GetSize(bits)) bits.push_back(extbit); } return RTLIL::Const(bits); @@ -933,15 +960,7 @@ RTLIL::Const AstNode::asAttrConst() const { log_assert(type == AST_CONSTANT); - RTLIL::Const val; - val.bits = bits; - - if (is_string) { - val.flags |= RTLIL::CONST_FLAG_STRING; - log_assert(val.decode_string() == str); - } - - return val; + return is_string ? RTLIL::Const(str) : RTLIL::Const(bits); } RTLIL::Const AstNode::asParaConst() const @@ -987,7 +1006,7 @@ uint64_t AstNode::asInt(bool is_signed) uint64_t ret = 0; for (int i = 0; i < 64; i++) - if (v.bits.at(i) == RTLIL::State::S1) + if (v.at(i) == RTLIL::State::S1) ret |= uint64_t(1) << i; return ret; @@ -1005,15 +1024,15 @@ double AstNode::asReal(bool is_signed) { RTLIL::Const val(bits); - bool is_negative = is_signed && !val.bits.empty() && val.bits.back() == RTLIL::State::S1; + bool is_negative = is_signed && !val.empty() && val.back() == RTLIL::State::S1; if (is_negative) - val = const_neg(val, val, false, false, val.bits.size()); + val = const_neg(val, val, false, false, val.size()); double v = 0; - for (size_t i = 0; i < val.bits.size(); i++) + for (auto i = 0; i < val.size(); i++) // IEEE Std 1800-2012 Par 6.12.2: Individual bits that are x or z in // the net or the variable shall be treated as zero upon conversion. - if (val.bits.at(i) == RTLIL::State::S1) + if (val.at(i) == RTLIL::State::S1) v += exp2(i); if (is_negative) v *= -1; @@ -1036,15 +1055,15 @@ RTLIL::Const AstNode::realAsConst(int width) #else if (!std::isfinite(v)) { #endif - result.bits = std::vector(width, RTLIL::State::Sx); + result = std::vector(width, RTLIL::State::Sx); } else { bool is_negative = v < 0; if (is_negative) v *= -1; for (int i = 0; i < width; i++, v /= 2) - result.bits.push_back((fmod(floor(v), 2) != 0) ? RTLIL::State::S1 : RTLIL::State::S0); + result.bits().push_back((fmod(floor(v), 2) != 0) ? RTLIL::State::S1 : RTLIL::State::S0); if (is_negative) - result = const_neg(result, result, false, false, result.bits.size()); + result = const_neg(result, result, false, false, result.size()); } return result; } @@ -1749,16 +1768,7 @@ static std::string serialize_param_value(const RTLIL::Const &val) { res.push_back('r'); res += stringf("%d", GetSize(val)); res.push_back('\''); - for (int i = GetSize(val) - 1; i >= 0; i--) { - switch (val.bits[i]) { - case RTLIL::State::S0: res.push_back('0'); break; - case RTLIL::State::S1: res.push_back('1'); break; - case RTLIL::State::Sx: res.push_back('x'); break; - case RTLIL::State::Sz: res.push_back('z'); break; - case RTLIL::State::Sa: res.push_back('?'); break; - case RTLIL::State::Sm: res.push_back('m'); break; - } - } + res.append(val.as_string("?")); return res; } @@ -1850,7 +1860,7 @@ std::string AstModule::derive_common(RTLIL::Design *design, const dictsecond.flags & RTLIL::CONST_FLAG_STRING) != 0) child->children[0] = AstNode::mkconst_str(it->second.decode_string()); else - child->children[0] = AstNode::mkconst_bits(it->second.bits, (it->second.flags & RTLIL::CONST_FLAG_SIGNED) != 0); + child->children[0] = AstNode::mkconst_bits(it->second.to_bits(), (it->second.flags & RTLIL::CONST_FLAG_SIGNED) != 0); rewritten.insert(it->first); } @@ -1863,7 +1873,7 @@ std::string AstModule::derive_common(RTLIL::Design *design, const dictchildren.push_back(AstNode::mkconst_str(param.second.decode_string())); else - defparam->children.push_back(AstNode::mkconst_bits(param.second.bits, (param.second.flags & RTLIL::CONST_FLAG_SIGNED) != 0)); + defparam->children.push_back(AstNode::mkconst_bits(param.second.to_bits(), (param.second.flags & RTLIL::CONST_FLAG_SIGNED) != 0)); new_ast->children.push_back(defparam); } diff --git a/frontends/ast/ast.h b/frontends/ast/ast.h index 6c4a1e15a..2c2d408ce 100644 --- a/frontends/ast/ast.h +++ b/frontends/ast/ast.h @@ -177,7 +177,7 @@ namespace AST { // for dict<> and pool<> unsigned int hashidx_; - unsigned int hash() const { return hashidx_; } + [[nodiscard]] Hasher hash_into(Hasher h) const { h.eat(hashidx_); return h; } // this nodes type AstNodeType type; @@ -410,6 +410,9 @@ namespace AST extern void (*set_line_num)(int); extern int (*get_line_num)(); + // for stats + unsigned long long astnode_count(); + // set set_line_num and get_line_num to internal dummy functions (done by simplify() and AstModule::derive // to control the filename and linenum properties of new nodes not generated by a frontend parser) void use_internal_line_num(); diff --git a/frontends/ast/dpicall.cc b/frontends/ast/dpicall.cc index 12a7e1183..d6fcc26bd 100644 --- a/frontends/ast/dpicall.cc +++ b/frontends/ast/dpicall.cc @@ -67,9 +67,10 @@ static ffi_fptr resolve_fn (std::string symbol_name) AST::AstNode *AST::dpi_call(const std::string &rtype, const std::string &fname, const std::vector &argtypes, const std::vector &args) { AST::AstNode *newNode = nullptr; - union { double f64; float f32; int32_t i32; void *ptr; } value_store [args.size() + 1]; - ffi_type *types [args.size() + 1]; - void *values [args.size() + 1]; + union value { double f64; float f32; int32_t i32; void *ptr; }; + std::vector value_store(args.size() + 1); + std::vector types(args.size() + 1); + std::vector values(args.size() + 1); ffi_cif cif; int status; @@ -118,10 +119,10 @@ AST::AstNode *AST::dpi_call(const std::string &rtype, const std::string &fname, log_error("invalid rtype '%s'.\n", rtype.c_str()); } - if ((status = ffi_prep_cif(&cif, FFI_DEFAULT_ABI, args.size(), types[args.size()], types)) != FFI_OK) + if ((status = ffi_prep_cif(&cif, FFI_DEFAULT_ABI, args.size(), types[args.size()], types.data())) != FFI_OK) log_error("ffi_prep_cif failed: status %d.\n", status); - ffi_call(&cif, resolve_fn(fname.c_str()), values[args.size()], values); + ffi_call(&cif, resolve_fn(fname.c_str()), values[args.size()], values.data()); if (rtype == "real") { newNode = new AstNode(AST_REALVALUE); diff --git a/frontends/ast/genrtlil.cc b/frontends/ast/genrtlil.cc index 3d47bd3c0..26ed0e3e4 100644 --- a/frontends/ast/genrtlil.cc +++ b/frontends/ast/genrtlil.cc @@ -735,10 +735,10 @@ struct AST_INTERNAL::ProcessGenerator for (auto sync : proc->syncs) { if (sync->type == RTLIL::STp) { triggers.append(sync->signal); - polarity.bits.push_back(RTLIL::S1); + polarity.bits().push_back(RTLIL::S1); } else if (sync->type == RTLIL::STn) { triggers.append(sync->signal); - polarity.bits.push_back(RTLIL::S0); + polarity.bits().push_back(RTLIL::S0); } } @@ -832,10 +832,10 @@ struct AST_INTERNAL::ProcessGenerator for (auto sync : proc->syncs) { if (sync->type == RTLIL::STp) { triggers.append(sync->signal); - polarity.bits.push_back(RTLIL::S1); + polarity.bits().push_back(RTLIL::S1); } else if (sync->type == RTLIL::STn) { triggers.append(sync->signal); - polarity.bits.push_back(RTLIL::S0); + polarity.bits().push_back(RTLIL::S0); } } @@ -892,7 +892,7 @@ struct AST_INTERNAL::ProcessGenerator RTLIL::Const priority_mask = RTLIL::Const(0, cur_idx); for (int i = 0; i < portid; i++) { int new_bit = port_map[std::make_pair(memid, i)]; - priority_mask.bits[new_bit] = orig_priority_mask.bits[i]; + priority_mask.bits()[new_bit] = orig_priority_mask[i]; } action.priority_mask = priority_mask; sync->mem_write_actions.push_back(action); @@ -984,7 +984,7 @@ void AstNode::detectSignWidthWorker(int &width_hint, bool &sign_hint, bool *foun // unallocated enum, ignore break; case AST_CONSTANT: - width_hint = max(width_hint, int(bits.size())); + width_hint = max(width_hint, GetSize(bits)); if (!is_signed) sign_hint = false; break; @@ -1446,6 +1446,7 @@ RTLIL::SigSpec AstNode::genRTLIL(int width_hint, bool sign_hint) wire->port_input = is_input; wire->port_output = is_output; wire->upto = range_swapped; + wire->is_signed = is_signed; for (auto &attr : attributes) { diff --git a/frontends/ast/simplify.cc b/frontends/ast/simplify.cc index 3d8478ef1..4d8c57ced 100644 --- a/frontends/ast/simplify.cc +++ b/frontends/ast/simplify.cc @@ -1433,6 +1433,7 @@ bool AstNode::simplify(bool const_fold, int stage, int width_hint, bool sign_hin current_ast_mod->children.push_back(wnode); } basic_prep = true; + is_custom_type = false; } break; @@ -1500,11 +1501,69 @@ bool AstNode::simplify(bool const_fold, int stage, int width_hint, bool sign_hin } break; + case AST_CAST_SIZE: { + int width = 1; + AstNode *node; + AstNode *child = children[0]; + + if (child->type == AST_WIRE) { + if (child->children.size() == 0) { + // Base type (e.g., int) + width = child->range_left - child->range_right +1; + node = mkconst_int(width, child->is_signed); + } else { + // User defined type + log_assert(child->children[0]->type == AST_WIRETYPE); + + const std::string &type_name = child->children[0]->str; + if (!current_scope.count(type_name)) + input_error("Unknown identifier `%s' used as type name\n", type_name.c_str()); + AstNode *resolved_type_node = current_scope.at(type_name); + if (resolved_type_node->type != AST_TYPEDEF) + input_error("`%s' does not name a type\n", type_name.c_str()); + log_assert(resolved_type_node->children.size() == 1); + AstNode *template_node = resolved_type_node->children[0]; + + // Ensure typedef itself is fully simplified + while (template_node->simplify(const_fold, stage, width_hint, sign_hint)) {}; + + switch (template_node->type) + { + case AST_WIRE: { + if (template_node->children.size() > 0 && template_node->children[0]->type == AST_RANGE) + width = range_width(this, template_node->children[0]); + child->delete_children(); + node = mkconst_int(width, true); + break; + } + + case AST_STRUCT: + case AST_UNION: { + child->delete_children(); + width = size_packed_struct(template_node, 0); + node = mkconst_int(width, false); + break; + } + + default: + log_error("Don't know how to translate static cast of type %s\n", type2str(template_node->type).c_str()); + } + } + + delete child; + children.erase(children.begin()); + children.insert(children.begin(), node); + } + + detect_width_simple = true; + children_are_self_determined = true; + break; + } + case AST_TO_BITS: case AST_TO_SIGNED: case AST_TO_UNSIGNED: case AST_SELFSZ: - case AST_CAST_SIZE: case AST_CONCAT: case AST_REPLICATE: case AST_REDUCE_AND: @@ -1660,8 +1719,8 @@ bool AstNode::simplify(bool const_fold, int stage, int width_hint, bool sign_hin if (v->type == AST_CONSTANT && v->bits_only_01()) { RTLIL::Const case_item_expr = v->bitsAsConst(width_hint, sign_hint); RTLIL::Const match = const_eq(case_expr, case_item_expr, sign_hint, sign_hint, 1); - log_assert(match.bits.size() == 1); - if (match.bits.front() == RTLIL::State::S1) { + log_assert(match.size() == 1); + if (match.front() == RTLIL::State::S1) { while (i+1 < GetSize(children)) delete children[++i]; goto keep_const_cond; @@ -1700,7 +1759,7 @@ bool AstNode::simplify(bool const_fold, int stage, int width_hint, bool sign_hin break; if (type == AST_GENBLOCK) break; - if (type == AST_CELLARRAY && children[i]->type == AST_CELL) + if (type == AST_CELLARRAY && (children[i]->type == AST_CELL || children[i]->type == AST_PRIMITIVE)) continue; if (type == AST_BLOCK && !str.empty()) break; @@ -1861,6 +1920,8 @@ bool AstNode::simplify(bool const_fold, int stage, int width_hint, bool sign_hin if (!str.empty() && str[0] == '\\' && (template_node->type == AST_STRUCT || template_node->type == AST_UNION)) { // replace instance with wire representing the packed structure newNode = make_packed_struct(template_node, str, attributes); + if (newNode->attributes.count(ID::wiretype)) + delete newNode->attributes[ID::wiretype]; newNode->set_attribute(ID::wiretype, mkconst_str(resolved_type_node->str)); // add original input/output attribute to resolved wire newNode->is_input = this->is_input; @@ -1872,6 +1933,8 @@ bool AstNode::simplify(bool const_fold, int stage, int width_hint, bool sign_hin // Prepare replacement node. newNode = template_node->clone(); newNode->str = str; + if (newNode->attributes.count(ID::wiretype)) + delete newNode->attributes[ID::wiretype]; newNode->set_attribute(ID::wiretype, mkconst_str(resolved_type_node->str)); newNode->is_input = is_input; newNode->is_output = is_output; @@ -1963,7 +2026,7 @@ bool AstNode::simplify(bool const_fold, int stage, int width_hint, bool sign_hin if (children[1]->type != AST_CONSTANT) input_error("Right operand of to_bits expression is not constant!\n"); RTLIL::Const new_value = children[1]->bitsAsConst(children[0]->bitsAsConst().as_int(), children[1]->is_signed); - newNode = mkconst_bits(new_value.bits, children[1]->is_signed); + newNode = mkconst_bits(new_value.to_bits(), children[1]->is_signed); goto apply_newNode; } @@ -2024,6 +2087,8 @@ bool AstNode::simplify(bool const_fold, int stage, int width_hint, bool sign_hin std::swap(range_left, range_right); range_swapped = force_upto; } + if (range_left == range_right && !attributes.count(ID::single_bit_vector)) + set_attribute(ID::single_bit_vector, mkconst_int(1, false)); } } else { if (!range_valid) @@ -2032,6 +2097,10 @@ bool AstNode::simplify(bool const_fold, int stage, int width_hint, bool sign_hin range_swapped = false; range_left = 0; range_right = 0; + if (attributes.count(ID::single_bit_vector)) { + delete attributes[ID::single_bit_vector]; + attributes.erase(ID::single_bit_vector); + } } } @@ -2126,7 +2195,7 @@ bool AstNode::simplify(bool const_fold, int stage, int width_hint, bool sign_hin log_file_warning(filename, location.first_line, "converting real value %e to binary %s.\n", children[0]->realvalue, log_signal(constvalue)); delete children[0]; - children[0] = mkconst_bits(constvalue.bits, sign_hint); + children[0] = mkconst_bits(constvalue.to_bits(), sign_hint); fixup_hierarchy_flags(); did_something = true; } @@ -2135,7 +2204,7 @@ bool AstNode::simplify(bool const_fold, int stage, int width_hint, bool sign_hin RTLIL::SigSpec sig(children[0]->bits); sig.extend_u0(width, children[0]->is_signed); AstNode *old_child_0 = children[0]; - children[0] = mkconst_bits(sig.as_const().bits, is_signed); + children[0] = mkconst_bits(sig.as_const().to_bits(), is_signed); delete old_child_0; fixup_hierarchy_flags(); } @@ -2683,6 +2752,7 @@ bool AstNode::simplify(bool const_fold, int stage, int width_hint, bool sign_hin if (new_cell->type == AST_PRIMITIVE) { input_error("Cell arrays of primitives are currently not supported.\n"); } else { + this->dumpAst(NULL, " "); log_assert(new_cell->children.at(0)->type == AST_CELLTYPE); new_cell->children.at(0)->str = stringf("$array:%d:%d:%s", i, num, new_cell->children.at(0)->str.c_str()); } @@ -2878,7 +2948,10 @@ bool AstNode::simplify(bool const_fold, int stage, int width_hint, bool sign_hin lsb_expr->children[stride_ix]->detectSignWidth(stride_width, stride_sign); max_width = std::max(i_width, stride_width); // Stride width calculated from actual stride value. - stride_width = std::ceil(std::log2(std::abs(stride))); + if (stride == 0) + stride_width = 0; + else + stride_width = std::ceil(std::log2(std::abs(stride))); if (i_width + stride_width > max_width) { // For (truncated) i*stride to be within the range of dst, the following must hold: @@ -3435,8 +3508,8 @@ skip_dynamic_range_lvalue_expansion:; delete buf; uint32_t result = 0; - for (size_t i = 0; i < arg_value.bits.size(); i++) - if (arg_value.bits.at(i) == RTLIL::State::S1) + for (auto i = 0; i < arg_value.size(); i++) + if (arg_value.at(i) == RTLIL::State::S1) result = i + 1; newNode = mkconst_int(result, true); @@ -4028,16 +4101,24 @@ skip_dynamic_range_lvalue_expansion:; delete arg; continue; } + AstNode *wire_id = new AstNode(AST_IDENTIFIER); wire_id->str = wire->str; - AstNode *assign = child->is_input ? - new AstNode(AST_ASSIGN_EQ, wire_id, arg) : - new AstNode(AST_ASSIGN_EQ, arg, wire_id); - assign->children[0]->was_checked = true; - if (child->is_input) + + if (child->is_input) { + AstNode *assign = new AstNode(AST_ASSIGN_EQ, wire_id->clone(), arg->clone()); + assign->children[0]->was_checked = true; new_stmts.push_back(assign); - else + } + + if (child->is_output) { + AstNode *assign = new AstNode(AST_ASSIGN_EQ, arg->clone(), wire_id->clone()); + assign->children[0]->was_checked = true; output_assignments.push_back(assign); + } + + delete arg; + delete wire_id; } } @@ -4115,14 +4196,14 @@ replace_fcall_later:; case AST_BIT_NOT: if (children[0]->type == AST_CONSTANT) { RTLIL::Const y = RTLIL::const_not(children[0]->bitsAsConst(width_hint, sign_hint), dummy_arg, sign_hint, false, width_hint); - newNode = mkconst_bits(y.bits, sign_hint); + newNode = mkconst_bits(y.to_bits(), sign_hint); } break; case AST_TO_SIGNED: case AST_TO_UNSIGNED: if (children[0]->type == AST_CONSTANT) { RTLIL::Const y = children[0]->bitsAsConst(width_hint, sign_hint); - newNode = mkconst_bits(y.bits, type == AST_TO_SIGNED); + newNode = mkconst_bits(y.to_bits(), type == AST_TO_SIGNED); } break; if (0) { case AST_BIT_AND: const_func = RTLIL::const_and; } @@ -4132,7 +4213,7 @@ replace_fcall_later:; if (children[0]->type == AST_CONSTANT && children[1]->type == AST_CONSTANT) { RTLIL::Const y = const_func(children[0]->bitsAsConst(width_hint, sign_hint), children[1]->bitsAsConst(width_hint, sign_hint), sign_hint, sign_hint, width_hint); - newNode = mkconst_bits(y.bits, sign_hint); + newNode = mkconst_bits(y.to_bits(), sign_hint); } break; if (0) { case AST_REDUCE_AND: const_func = RTLIL::const_reduce_and; } @@ -4142,13 +4223,13 @@ replace_fcall_later:; if (0) { case AST_REDUCE_BOOL: const_func = RTLIL::const_reduce_bool; } if (children[0]->type == AST_CONSTANT) { RTLIL::Const y = const_func(RTLIL::Const(children[0]->bits), dummy_arg, false, false, -1); - newNode = mkconst_bits(y.bits, false); + newNode = mkconst_bits(y.to_bits(), false); } break; case AST_LOGIC_NOT: if (children[0]->type == AST_CONSTANT) { RTLIL::Const y = RTLIL::const_logic_not(RTLIL::Const(children[0]->bits), dummy_arg, children[0]->is_signed, false, -1); - newNode = mkconst_bits(y.bits, false); + newNode = mkconst_bits(y.to_bits(), false); } else if (children[0]->isConst()) { newNode = mkconst_int(children[0]->asReal(sign_hint) == 0, false, 1); @@ -4159,7 +4240,7 @@ replace_fcall_later:; if (children[0]->type == AST_CONSTANT && children[1]->type == AST_CONSTANT) { RTLIL::Const y = const_func(RTLIL::Const(children[0]->bits), RTLIL::Const(children[1]->bits), children[0]->is_signed, children[1]->is_signed, -1); - newNode = mkconst_bits(y.bits, false); + newNode = mkconst_bits(y.to_bits(), false); } else if (children[0]->isConst() && children[1]->isConst()) { if (type == AST_LOGIC_AND) @@ -4176,7 +4257,7 @@ replace_fcall_later:; if (children[0]->type == AST_CONSTANT && children[1]->type == AST_CONSTANT) { RTLIL::Const y = const_func(children[0]->bitsAsConst(width_hint, sign_hint), RTLIL::Const(children[1]->bits), sign_hint, type == AST_POW ? children[1]->is_signed : false, width_hint); - newNode = mkconst_bits(y.bits, sign_hint); + newNode = mkconst_bits(y.to_bits(), sign_hint); } else if (type == AST_POW && children[0]->isConst() && children[1]->isConst()) { newNode = new AstNode(AST_REALVALUE); @@ -4196,7 +4277,7 @@ replace_fcall_later:; bool cmp_signed = children[0]->is_signed && children[1]->is_signed; RTLIL::Const y = const_func(children[0]->bitsAsConst(cmp_width, cmp_signed), children[1]->bitsAsConst(cmp_width, cmp_signed), cmp_signed, cmp_signed, 1); - newNode = mkconst_bits(y.bits, false); + newNode = mkconst_bits(y.to_bits(), false); } else if (children[0]->isConst() && children[1]->isConst()) { bool cmp_signed = (children[0]->type == AST_REALVALUE || children[0]->is_signed) && (children[1]->type == AST_REALVALUE || children[1]->is_signed); @@ -4221,7 +4302,7 @@ replace_fcall_later:; if (children[0]->type == AST_CONSTANT && children[1]->type == AST_CONSTANT) { RTLIL::Const y = const_func(children[0]->bitsAsConst(width_hint, sign_hint), children[1]->bitsAsConst(width_hint, sign_hint), sign_hint, sign_hint, width_hint); - newNode = mkconst_bits(y.bits, sign_hint); + newNode = mkconst_bits(y.to_bits(), sign_hint); } else if (children[0]->isConst() && children[1]->isConst()) { newNode = new AstNode(AST_REALVALUE); @@ -4240,7 +4321,7 @@ replace_fcall_later:; if (0) { case AST_NEG: const_func = RTLIL::const_neg; } if (children[0]->type == AST_CONSTANT) { RTLIL::Const y = const_func(children[0]->bitsAsConst(width_hint, sign_hint), dummy_arg, sign_hint, false, width_hint); - newNode = mkconst_bits(y.bits, sign_hint); + newNode = mkconst_bits(y.to_bits(), sign_hint); } else if (children[0]->isConst()) { newNode = new AstNode(AST_REALVALUE); @@ -4268,10 +4349,10 @@ replace_fcall_later:; newNode->realvalue = choice->asReal(sign_hint); } else { RTLIL::Const y = choice->bitsAsConst(width_hint, sign_hint); - if (choice->is_string && y.bits.size() % 8 == 0 && sign_hint == false) - newNode = mkconst_str(y.bits); + if (choice->is_string && y.size() % 8 == 0 && sign_hint == false) + newNode = mkconst_str(y.to_bits()); else - newNode = mkconst_bits(y.bits, sign_hint); + newNode = mkconst_bits(y.to_bits(), sign_hint); } } else if (choice->isConst()) { @@ -4280,11 +4361,11 @@ replace_fcall_later:; } else if (children[1]->type == AST_CONSTANT && children[2]->type == AST_CONSTANT) { RTLIL::Const a = children[1]->bitsAsConst(width_hint, sign_hint); RTLIL::Const b = children[2]->bitsAsConst(width_hint, sign_hint); - log_assert(a.bits.size() == b.bits.size()); - for (size_t i = 0; i < a.bits.size(); i++) - if (a.bits[i] != b.bits[i]) - a.bits[i] = RTLIL::State::Sx; - newNode = mkconst_bits(a.bits, sign_hint); + log_assert(a.size() == b.size()); + for (auto i = 0; i < a.size(); i++) + if (a[i] != b[i]) + a.bits()[i] = RTLIL::State::Sx; + newNode = mkconst_bits(a.to_bits(), sign_hint); } else if (children[1]->isConst() && children[2]->isConst()) { newNode = new AstNode(AST_REALVALUE); if (children[1]->asReal(sign_hint) == children[2]->asReal(sign_hint)) @@ -4305,7 +4386,7 @@ replace_fcall_later:; val = children[1]->bitsAsUnsizedConst(width); else val = children[1]->bitsAsConst(width); - newNode = mkconst_bits(val.bits, children[1]->is_signed); + newNode = mkconst_bits(val.to_bits(), children[1]->is_signed); } break; case AST_CONCAT: @@ -4890,7 +4971,7 @@ bool AstNode::mem2reg_as_needed_pass2(pool &mem2reg_set, AstNode *mod, target->str = str; target->id2ast = id2ast; target->was_checked = true; - block->children.push_back(new AstNode(AST_ASSIGN_EQ, target, mkconst_bits(data.extract(i*wordsz + pos, clen).bits, false))); + block->children.push_back(new AstNode(AST_ASSIGN_EQ, target, mkconst_bits(data.extract(i*wordsz + pos, clen).to_bits(), false))); pos = epos; } } @@ -5245,7 +5326,7 @@ bool AstNode::is_simple_const_expr() bool AstNode::replace_variables(std::map &variables, AstNode *fcall, bool must_succeed) { if (type == AST_IDENTIFIER && variables.count(str)) { - int offset = variables.at(str).offset, width = variables.at(str).val.bits.size(); + int offset = variables.at(str).offset, width = variables.at(str).val.size(); if (!children.empty()) { if (children.size() != 1 || children.at(0)->type != AST_RANGE) { if (!must_succeed) @@ -5268,7 +5349,7 @@ bool AstNode::replace_variables(std::map &varia offset -= variables.at(str).offset; if (variables.at(str).range_swapped) offset = -offset; - std::vector &var_bits = variables.at(str).val.bits; + std::vector &var_bits = variables.at(str).val.bits(); std::vector new_bits(var_bits.begin() + offset, var_bits.begin() + offset + width); AstNode *newNode = mkconst_bits(new_bits, variables.at(str).is_signed); newNode->cloneInto(this); @@ -5399,7 +5480,7 @@ AstNode *AstNode::eval_const_function(AstNode *fcall, bool must_succeed) } if (stmt->children.at(0)->children.empty()) { - variables[stmt->children.at(0)->str].val = stmt->children.at(1)->bitsAsConst(variables[stmt->children.at(0)->str].val.bits.size()); + variables[stmt->children.at(0)->str].val = stmt->children.at(1)->bitsAsConst(variables[stmt->children.at(0)->str].val.size()); } else { AstNode *range = stmt->children.at(0)->children.at(0); if (!range->range_valid) { @@ -5410,12 +5491,12 @@ AstNode *AstNode::eval_const_function(AstNode *fcall, bool must_succeed) int offset = min(range->range_left, range->range_right); int width = std::abs(range->range_left - range->range_right) + 1; varinfo_t &v = variables[stmt->children.at(0)->str]; - RTLIL::Const r = stmt->children.at(1)->bitsAsConst(v.val.bits.size()); + RTLIL::Const r = stmt->children.at(1)->bitsAsConst(v.val.size()); for (int i = 0; i < width; i++) { int index = i + offset - v.offset; if (v.range_swapped) index = -index; - v.val.bits.at(index) = r.bits.at(i); + v.val.bits().at(index) = r.at(i); } } @@ -5558,7 +5639,7 @@ AstNode *AstNode::eval_const_function(AstNode *fcall, bool must_succeed) log_abort(); } - result = AstNode::mkconst_bits(variables.at(str).val.bits, variables.at(str).is_signed); + result = AstNode::mkconst_bits(variables.at(str).val.to_bits(), variables.at(str).is_signed); finished: delete block; diff --git a/frontends/blif/blifparse.cc b/frontends/blif/blifparse.cc index 731656866..f6b894563 100644 --- a/frontends/blif/blifparse.cc +++ b/frontends/blif/blifparse.cc @@ -149,7 +149,7 @@ void parse_blif(RTLIL::Design *design, std::istream &f, IdString dff_name, bool if (buffer[0] == '.') { if (lutptr) { - for (auto &bit : lutptr->bits) + for (auto &bit : lutptr->bits()) if (bit == RTLIL::State::Sx) bit = lut_default_state; lutptr = NULL; @@ -321,9 +321,9 @@ void parse_blif(RTLIL::Design *design, std::istream &f, IdString dff_name, bool const_v = Const(str); } else { int n = strlen(v); - const_v.bits.resize(n); + const_v.bits().resize(n); for (int i = 0; i < n; i++) - const_v.bits[i] = v[n-i-1] != '0' ? State::S1 : State::S0; + const_v.bits()[i] = v[n-i-1] != '0' ? State::S1 : State::S0; } if (!strcmp(cmd, ".attr")) { if (obj_attributes == nullptr) { @@ -566,16 +566,16 @@ void parse_blif(RTLIL::Design *design, std::istream &f, IdString dff_name, bool for (int i = 0; i < input_len; i++) switch (input[i]) { case '0': - sopcell->parameters[ID::TABLE].bits.push_back(State::S1); - sopcell->parameters[ID::TABLE].bits.push_back(State::S0); + sopcell->parameters[ID::TABLE].bits().push_back(State::S1); + sopcell->parameters[ID::TABLE].bits().push_back(State::S0); break; case '1': - sopcell->parameters[ID::TABLE].bits.push_back(State::S0); - sopcell->parameters[ID::TABLE].bits.push_back(State::S1); + sopcell->parameters[ID::TABLE].bits().push_back(State::S0); + sopcell->parameters[ID::TABLE].bits().push_back(State::S1); break; default: - sopcell->parameters[ID::TABLE].bits.push_back(State::S0); - sopcell->parameters[ID::TABLE].bits.push_back(State::S0); + sopcell->parameters[ID::TABLE].bits().push_back(State::S0); + sopcell->parameters[ID::TABLE].bits().push_back(State::S0); break; } @@ -605,7 +605,7 @@ void parse_blif(RTLIL::Design *design, std::istream &f, IdString dff_name, bool goto try_next_value; } } - lutptr->bits.at(i) = !strcmp(output, "0") ? RTLIL::State::S0 : RTLIL::State::S1; + lutptr->bits().at(i) = !strcmp(output, "0") ? RTLIL::State::S0 : RTLIL::State::S1; try_next_value:; } diff --git a/frontends/liberty/liberty.cc b/frontends/liberty/liberty.cc index 16fed54f2..3228f02fb 100644 --- a/frontends/liberty/liberty.cc +++ b/frontends/liberty/liberty.cc @@ -348,7 +348,7 @@ static bool create_latch(RTLIL::Module *module, const LibertyAst *node, bool fla RTLIL::Cell *enable_gate = module->addCell(NEW_ID, enable_polarity ? ID($_OR_) : ID($_AND_)); enable_gate->setPort(ID::A, enable_sig); enable_gate->setPort(ID::B, clear_enable); - enable_gate->setPort(ID::Y, data_sig = module->addWire(NEW_ID)); + enable_gate->setPort(ID::Y, enable_sig = module->addWire(NEW_ID)); } if (preset_sig.size() == 1) @@ -376,7 +376,7 @@ static bool create_latch(RTLIL::Module *module, const LibertyAst *node, bool fla RTLIL::Cell *enable_gate = module->addCell(NEW_ID, enable_polarity ? ID($_OR_) : ID($_AND_)); enable_gate->setPort(ID::A, enable_sig); enable_gate->setPort(ID::B, preset_enable); - enable_gate->setPort(ID::Y, data_sig = module->addWire(NEW_ID)); + enable_gate->setPort(ID::Y, enable_sig = module->addWire(NEW_ID)); } cell = module->addCell(NEW_ID, stringf("$_DLATCH_%c_", enable_polarity ? 'P' : 'N')); @@ -462,9 +462,15 @@ struct LibertyFrontend : public Frontend { log(" -ignore_miss_data_latch\n"); log(" ignore latches with missing data and/or enable pins\n"); log("\n"); + log(" -ignore_buses\n"); + log(" ignore cells with bus interfaces (wide ports)\n"); + log("\n"); log(" -setattr \n"); log(" set the specified attribute (to the value 1) on all loaded modules\n"); log("\n"); + log(" -unit_delay\n"); + log(" import combinational timing arcs under the unit delay model\n"); + log("\n"); } void execute(std::istream *&f, std::string filename, std::vector args, RTLIL::Design *design) override { @@ -475,6 +481,8 @@ struct LibertyFrontend : public Frontend { bool flag_ignore_miss_func = false; bool flag_ignore_miss_dir = false; bool flag_ignore_miss_data_latch = false; + bool flag_ignore_buses = false; + bool flag_unit_delay = false; std::vector attributes; size_t argidx; @@ -510,10 +518,18 @@ struct LibertyFrontend : public Frontend { flag_ignore_miss_data_latch = true; continue; } + if (arg == "-ignore_buses") { + flag_ignore_buses = true; + continue; + } if (arg == "-setattr" && argidx+1 < args.size()) { attributes.push_back(RTLIL::escape_id(args[++argidx])); continue; } + if (arg == "-unit_delay") { + flag_unit_delay = true; + continue; + } break; } extra_args(f, filename, args, argidx); @@ -523,7 +539,7 @@ struct LibertyFrontend : public Frontend { log_header(design, "Executing Liberty frontend: %s\n", filename.c_str()); - LibertyParser parser(*f); + LibertyParser parser(*f, filename); int cell_count = 0; std::map> global_type_map; @@ -534,27 +550,13 @@ struct LibertyFrontend : public Frontend { if (cell->id != "cell" || cell->args.size() != 1) continue; - std::string cell_name = RTLIL::escape_id(cell->args.at(0)); - - if (design->has(cell_name)) { - Module *existing_mod = design->module(cell_name); - if (!flag_nooverwrite && !flag_overwrite && !existing_mod->get_bool_attribute(ID::blackbox)) { - log_error("Re-definition of cell/module %s!\n", log_id(cell_name)); - } else if (flag_nooverwrite) { - log("Ignoring re-definition of module %s.\n", log_id(cell_name)); - continue; - } else { - log("Replacing existing%s module %s.\n", existing_mod->get_bool_attribute(ID::blackbox) ? " blackbox" : "", log_id(cell_name)); - design->remove(existing_mod); - } - } - // log("Processing cell type %s.\n", RTLIL::unescape_id(cell_name).c_str()); std::map> type_map = global_type_map; parse_type_map(type_map, cell); RTLIL::Module *module = new RTLIL::Module; + std::string cell_name = RTLIL::escape_id(cell->args.at(0)); module->name = cell_name; if (flag_lib) @@ -563,9 +565,15 @@ struct LibertyFrontend : public Frontend { if (flag_wb) module->set_bool_attribute(ID::whitebox); + const LibertyAst *area = cell->find("area"); + if (area) + module->attributes[ID::area] = area->value; + for (auto &attr : attributes) module->attributes[attr] = 1; + bool simple_comb_cell = true, has_outputs = false; + for (auto node : cell->children) { if (node->id == "pin" && node->args.size() == 1) { @@ -587,6 +595,12 @@ struct LibertyFrontend : public Frontend { if (node->id == "bus" && node->args.size() == 1) { + if (flag_ignore_buses) { + log("Ignoring cell %s with a bus interface %s.\n", log_id(module->name), node->args.at(0).c_str()); + delete module; + goto skip_cell; + } + if (!flag_lib) log_error("Error in cell %s: bus interfaces are only supported in -lib mode.\n", log_id(cell_name)); @@ -601,6 +615,8 @@ struct LibertyFrontend : public Frontend { if (!dir || (dir->value != "input" && dir->value != "output" && dir->value != "inout" && dir->value != "internal")) log_error("Missing or invalid direction for bus %s on cell %s.\n", node->args.at(0).c_str(), log_id(module->name)); + simple_comb_cell = false; + if (dir->value == "internal") continue; @@ -648,10 +664,18 @@ struct LibertyFrontend : public Frontend { { const LibertyAst *dir = node->find("direction"); + if (dir->value == "internal" || dir->value == "inout") + simple_comb_cell = false; + if (flag_lib && dir->value == "internal") continue; RTLIL::Wire *wire = module->wires_.at(RTLIL::escape_id(node->args.at(0))); + log_assert(wire); + + const LibertyAst *capacitance = node->find("capacitance"); + if (capacitance) + wire->attributes[ID::capacitance] = capacitance->value; if (dir && dir->value == "inout") { wire->port_input = true; @@ -663,8 +687,10 @@ struct LibertyFrontend : public Frontend { continue; } - if (dir && dir->value == "output") + if (dir && dir->value == "output") { + has_outputs = true; wire->port_output = true; + } if (flag_lib) continue; @@ -682,15 +708,64 @@ struct LibertyFrontend : public Frontend { goto skip_cell; } } + simple_comb_cell = false; } else { RTLIL::SigSpec out_sig = parse_func_expr(module, func->value.c_str()); const LibertyAst *three_state = node->find("three_state"); if (three_state) { out_sig = create_tristate(module, out_sig, three_state->value.c_str()); + simple_comb_cell = false; } module->connect(RTLIL::SigSig(wire, out_sig)); } } + + if (node->id == "ff" || node->id == "ff_bank" || + node->id == "latch" || node->id == "latch_bank" || + node->id == "statetable") + simple_comb_cell = false; + } + + if (simple_comb_cell && has_outputs) { + module->set_bool_attribute(ID::abc9_box); + + if (flag_unit_delay) { + for (auto wi : module->wires()) + if (wi->port_input) { + for (auto wo : module->wires()) + if (wo->port_output) { + RTLIL::Cell *spec = module->addCell(NEW_ID, ID($specify2)); + spec->setParam(ID::SRC_WIDTH, wi->width); + spec->setParam(ID::DST_WIDTH, wo->width); + spec->setParam(ID::T_FALL_MAX, 1000); + spec->setParam(ID::T_FALL_TYP, 1000); + spec->setParam(ID::T_FALL_MIN, 1000); + spec->setParam(ID::T_RISE_MAX, 1000); + spec->setParam(ID::T_RISE_TYP, 1000); + spec->setParam(ID::T_RISE_MIN, 1000); + spec->setParam(ID::SRC_DST_POL, false); + spec->setParam(ID::SRC_DST_PEN, false); + spec->setParam(ID::FULL, true); + spec->setPort(ID::EN, Const(1, 1)); + spec->setPort(ID::SRC, wi); + spec->setPort(ID::DST, wo); + } + } + } + } + + if (design->has(cell_name)) { + Module *existing_mod = design->module(cell_name); + if (!flag_nooverwrite && !flag_overwrite && !existing_mod->get_bool_attribute(ID::blackbox)) { + log_error("Re-definition of cell/module %s!\n", log_id(cell_name)); + } else if (flag_nooverwrite) { + log("Ignoring re-definition of module %s.\n", log_id(cell_name)); + delete module; + goto skip_cell; + } else { + log("Replacing existing%s module %s.\n", existing_mod->get_bool_attribute(ID::blackbox) ? " blackbox" : "", log_id(cell_name)); + design->remove(existing_mod); + } } module->fixup_ports(); diff --git a/frontends/rtlil/rtlil_frontend.cc b/frontends/rtlil/rtlil_frontend.cc index 5f85ca2b8..2c1910d13 100644 --- a/frontends/rtlil/rtlil_frontend.cc +++ b/frontends/rtlil/rtlil_frontend.cc @@ -31,6 +31,11 @@ void rtlil_frontend_yyerror(char const *s) YOSYS_NAMESPACE_PREFIX log_error("Parser error in line %d: %s\n", rtlil_frontend_yyget_lineno(), s); } +void rtlil_frontend_yywarning(char const *s) +{ + YOSYS_NAMESPACE_PREFIX log_warning("In line %d: %s\n", rtlil_frontend_yyget_lineno(), s); +} + YOSYS_NAMESPACE_BEGIN struct RTLILFrontend : public Frontend { @@ -96,20 +101,5 @@ struct RTLILFrontend : public Frontend { } } RTLILFrontend; -struct IlangFrontend : public Frontend { - IlangFrontend() : Frontend("ilang", "(deprecated) alias of read_rtlil") { } - void help() override - { - // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| - log("\n"); - log("See `help read_rtlil`.\n"); - log("\n"); - } - void execute(std::istream *&f, std::string filename, std::vector args, RTLIL::Design *design) override - { - RTLILFrontend.execute(f, filename, args, design); - } -} IlangFrontend; - YOSYS_NAMESPACE_END diff --git a/frontends/rtlil/rtlil_frontend.h b/frontends/rtlil/rtlil_frontend.h index 189260605..31cfb80b4 100644 --- a/frontends/rtlil/rtlil_frontend.h +++ b/frontends/rtlil/rtlil_frontend.h @@ -42,6 +42,7 @@ YOSYS_NAMESPACE_END extern int rtlil_frontend_yydebug; int rtlil_frontend_yylex(void); void rtlil_frontend_yyerror(char const *s); +void rtlil_frontend_yywarning(char const *s); void rtlil_frontend_yyrestart(FILE *f); int rtlil_frontend_yyparse(void); int rtlil_frontend_yylex_destroy(void); diff --git a/frontends/rtlil/rtlil_parser.y b/frontends/rtlil/rtlil_parser.y index 3d9862ebb..fc7615364 100644 --- a/frontends/rtlil/rtlil_parser.y +++ b/frontends/rtlil/rtlil_parser.y @@ -344,6 +344,16 @@ assign_stmt: TOK_ASSIGN sigspec sigspec EOL { if (attrbuf.size() != 0) rtlil_frontend_yyerror("dangling attribute"); + + // See https://github.com/YosysHQ/yosys/pull/4765 for discussion on this + // warning + if (!switch_stack.back()->empty()) { + rtlil_frontend_yywarning( + "case rule assign statements after switch statements may cause unexpected behaviour. " + "The assign statement is reordered to come before all switch statements." + ); + } + case_stack.back()->actions.push_back(RTLIL::SigSig(*$2, *$3)); delete $2; delete $3; @@ -447,7 +457,7 @@ constant: bits.pop_back(); $$ = new RTLIL::Const; for (auto it = bits.begin(); it != bits.end(); it++) - $$->bits.push_back(*it); + $$->bits().push_back(*it); if (is_signed) { $$->flags |= RTLIL::CONST_FLAG_SIGNED; } diff --git a/frontends/verific/verific.cc b/frontends/verific/verific.cc index 2dd8aa095..7284c7cd9 100644 --- a/frontends/verific/verific.cc +++ b/frontends/verific/verific.cc @@ -21,6 +21,7 @@ #include "kernel/sigtools.h" #include "kernel/celltypes.h" #include "kernel/log.h" +#include "kernel/utils.h" #include "libs/sha1/sha1.h" #include #include @@ -122,7 +123,7 @@ void msg_func(msg_type_t msg_type, const char *message_id, linefile_type linefil msg_type == VERIFIC_IGNORE ? "IGNORE" : msg_type == VERIFIC_INFO ? "INFO" : msg_type == VERIFIC_COMMENT ? "COMMENT" : - msg_type == VERIFIC_PROGRAM_ERROR ? "PROGRAM_ERROR" : "UNKNOWN", message_id); + msg_type == VERIFIC_PROGRAM_ERROR ? "PROGRAM_ERROR" : "UNKNOWN", message_id ? message_id : ""); string message = linefile ? stringf("%s:%d: ", LineFile::GetFileName(linefile), LineFile::GetLineNo(linefile)) : ""; message += vstringf(msg, args); @@ -236,23 +237,6 @@ RTLIL::IdString VerificImporter::new_verific_id(Verific::DesignObj *obj) return s; } -RTLIL::Const mkconst_str(const std::string &str) -{ - RTLIL::Const val; - std::vector data; - data.reserve(str.size() * 8); - for (size_t i = 0; i < str.size(); i++) { - unsigned char ch = str[str.size() - i - 1]; - for (int j = 0; j < 8; j++) { - data.push_back((ch & 1) ? State::S1 : State::S0); - ch = ch >> 1; - } - } - val.bits = data; - val.flags |= RTLIL::CONST_FLAG_STRING; - return val; -} - static const RTLIL::Const extract_vhdl_boolean(std::string &val) { if (val == "false") @@ -295,7 +279,7 @@ static const RTLIL::Const extract_vhdl_char(std::string &val) static const RTLIL::Const extract_real_value(std::string &val) { - RTLIL::Const c = mkconst_str(val); + RTLIL::Const c(val); c.flags |= RTLIL::CONST_FLAG_REAL; return c; } @@ -333,7 +317,7 @@ static const RTLIL::Const extract_vhdl_const(const char *value, bool output_sig } else if (val == "true") { c = RTLIL::Const::from_string("1"); } else { - c = mkconst_str(val); + c = RTLIL::Const(val); log_warning("encoding value '%s' as string.\n", value); } if (is_signed) @@ -364,7 +348,7 @@ static const RTLIL::Const extract_verilog_const(const char *value, bool allow_s } else if (allow_string) { c = RTLIL::Const(val); } else { - c = mkconst_str(val); + c = RTLIL::Const(val); log_warning("encoding value '%s' as string.\n", value); } if (is_signed) @@ -424,7 +408,7 @@ static const std::string verific_unescape(const char *value) } #endif -void VerificImporter::import_attributes(dict &attributes, DesignObj *obj, Netlist *nl) +void VerificImporter::import_attributes(dict &attributes, DesignObj *obj, Netlist *nl, int wire_width_hint) { if (!obj) return; @@ -450,6 +434,27 @@ void VerificImporter::import_attributes(dict &att auto type_range = nl->GetTypeRange(obj->Name()); if (!type_range) return; + if (nl->IsFromVhdl() && type_range->IsTypeScalar()) { + const long long bottom_bound = type_range->GetScalarRangeLeftBound(); + const long long top_bound = type_range->GetScalarRangeRightBound(); + int bit_width = type_range->LeftRangeBound()+1; + if (bit_width <= 0) { // VHDL null range + if (wire_width_hint >= 0) + bit_width = wire_width_hint; + else + bit_width = 64; //fallback, currently largest integer width that verific will allow (in vhdl2019 mode) + } else { + if (wire_width_hint >= 0) log_assert(bit_width == wire_width_hint); + } + RTLIL::Const bottom_const(bottom_bound, bit_width); + RTLIL::Const top_const(top_bound, bit_width); + if (bottom_bound < 0 || top_bound < 0) { + bottom_const.flags |= RTLIL::CONST_FLAG_SIGNED; + top_const.flags |= RTLIL::CONST_FLAG_SIGNED; + } + attributes.emplace(ID(bottom_bound), bottom_const); + attributes.emplace(ID(top_bound), top_const); + } if (!type_range->IsTypeEnum()) return; #ifdef VERIFIC_VHDL_SUPPORT @@ -615,7 +620,7 @@ RTLIL::SigSpec VerificImporter::operatorInportCase(Instance *inst, const char *p } } -RTLIL::SigSpec VerificImporter::operatorOutput(Instance *inst, const pool *any_all_nets) +RTLIL::SigSpec VerificImporter::operatorOutput(Instance *inst, const pool *any_all_nets) { RTLIL::SigSpec sig; RTLIL::Wire *dummy_wire = NULL; @@ -1441,6 +1446,25 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma module_name = "\\" + sha1_if_contain_spaces(module_name); } + { + Array ram_nets ; + MapIter mem_mi; + Net *mem_net; + FOREACH_NET_OF_NETLIST(nl, mem_mi, mem_net) + { + if (!mem_net->IsRamNet()) continue ; + + if (mem_net->GetAtt("mem2reg")) + ram_nets.Insert(mem_net) ; + } + unsigned i ; + FOREACH_ARRAY_ITEM(&ram_nets, i, mem_net) { + log("Bit blasting RAM for identifier '%s'\n", mem_net->Name()); + mem_net->BlastNet(); + } + nl->RemoveDanglingLogic(0); + } + netlist = nl; if (design->has(module_name)) { @@ -1460,7 +1484,8 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma log("Importing module %s.\n", RTLIL::id2cstr(module->name)); } import_attributes(module->attributes, nl, nl); - module->set_string_attribute(ID::hdlname, nl->CellBaseName()); + if (module->name.isPublic()) + module->set_string_attribute(ID::hdlname, nl->CellBaseName()); module->set_string_attribute(ID(library), nl->Owner()->Owner()->Name()); #ifdef VERIFIC_VHDL_SUPPORT if (nl->IsFromVhdl()) { @@ -1475,7 +1500,8 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma FOREACH_PARAMETER_OF_NETLIST(nl, mi, param_name, param_value) { module->avail_parameters(RTLIL::escape_id(param_name)); const TypeRange *tr = nl->GetTypeRange(param_name) ; - module->parameter_default_values[RTLIL::escape_id(param_name)] = verific_const(tr->GetTypeName(), param_value, nl); + const char* type_name = (tr) ? tr->GetTypeName() : nullptr; + module->parameter_default_values[RTLIL::escape_id(param_name)] = verific_const(type_name, param_value, nl); } SetIter si; @@ -1502,7 +1528,7 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma log(" importing port %s.\n", port->Name()); RTLIL::Wire *wire = module->addWire(RTLIL::escape_id(port->Name())); - import_attributes(wire->attributes, port, nl); + import_attributes(wire->attributes, port, nl, 1); wire->port_id = nl->IndexOf(port) + 1; @@ -1530,11 +1556,13 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma RTLIL::Wire *wire = module->addWire(RTLIL::escape_id(portbus->Name()), portbus->Size()); wire->start_offset = min(portbus->LeftIndex(), portbus->RightIndex()); wire->upto = portbus->IsUp(); - import_attributes(wire->attributes, portbus, nl); + import_attributes(wire->attributes, portbus, nl, portbus->Size()); + if (portbus->Size() == 1) + wire->set_bool_attribute(ID::single_bit_vector); SetIter si ; Port *port ; FOREACH_PORT_OF_PORTBUS(portbus, si, port) { - import_attributes(wire->attributes, port->GetNet(), nl); + import_attributes(wire->attributes, port->GetNet(), nl, portbus->Size()); break; } bool portbus_input = portbus->GetDir() == DIR_INOUT || portbus->GetDir() == DIR_IN; @@ -1571,9 +1599,9 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma module->fixup_ports(); - dict init_nets; - pool anyconst_nets, anyseq_nets; - pool allconst_nets, allseq_nets; + dict init_nets; + pool anyconst_nets, anyseq_nets; + pool allconst_nets, allseq_nets; any_all_nets.clear(); FOREACH_NET_OF_NETLIST(nl, mi, net) @@ -1621,7 +1649,7 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma if (*ascii_initdata == 0) break; if (*ascii_initdata == '0' || *ascii_initdata == '1') { - initval[bit_idx] = (*ascii_initdata == '0') ? State::S0 : State::S1; + initval.bits()[bit_idx] = (*ascii_initdata == '0') ? State::S0 : State::S1; initval_valid = true; } ascii_initdata++; @@ -1696,7 +1724,7 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma log(" importing net %s as %s.\n", net->Name(), log_id(wire_name)); RTLIL::Wire *wire = module->addWire(wire_name); - import_attributes(wire->attributes, net, nl); + import_attributes(wire->attributes, net, nl, 1); net_map[net] = wire; } @@ -1725,10 +1753,12 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma MapIter mibus; FOREACH_NET_OF_NETBUS(netbus, mibus, net) { if (net) - import_attributes(wire->attributes, net, nl); + import_attributes(wire->attributes, net, nl, netbus->Size()); break; } - import_attributes(wire->attributes, netbus, nl); + import_attributes(wire->attributes, netbus, nl, netbus->Size()); + if (netbus->Size() == 1) + wire->set_bool_attribute(ID::single_bit_vector); RTLIL::Const initval = Const(State::Sx, GetSize(wire)); bool initval_valid = false; @@ -1743,9 +1773,9 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma if (init_nets.count(net)) { if (init_nets.at(net) == '0') - initval.bits.at(bitidx) = State::S0; + initval.bits().at(bitidx) = State::S0; if (init_nets.at(net) == '1') - initval.bits.at(bitidx) = State::S1; + initval.bits().at(bitidx) = State::S1; initval_valid = true; init_nets.erase(net); } @@ -1819,12 +1849,12 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma initval = bit.wire->attributes.at(ID::init); while (GetSize(initval) < GetSize(bit.wire)) - initval.bits.push_back(State::Sx); + initval.bits().push_back(State::Sx); if (it.second == '0') - initval.bits.at(bit.offset) = State::S0; + initval.bits().at(bit.offset) = State::S0; if (it.second == '1') - initval.bits.at(bit.offset) = State::S1; + initval.bits().at(bit.offset) = State::S1; bit.wire->attributes[ID::init] = initval; } @@ -1836,10 +1866,10 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma module->connect(net_map_at(net), module->Anyseq(new_verific_id(net))); #ifdef VERIFIC_SYSTEMVERILOG_SUPPORT - pool sva_asserts; - pool sva_assumes; - pool sva_covers; - pool sva_triggers; + pool sva_asserts; + pool sva_assumes; + pool sva_covers; + pool sva_triggers; #endif pool past_ffs; @@ -2011,7 +2041,7 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma } Const qx_init = Const(State::S1, width); - qx_init.bits.resize(2 * width, State::S0); + qx_init.bits().resize(2 * width, State::S0); clocking.addDff(new_verific_id(inst), sig_dx, sig_qx, qx_init); module->addXnor(new_verific_id(inst), sig_dx, sig_qx, sig_ox); @@ -2129,14 +2159,7 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma if (verific_verbose) log(" assert condition %s.\n", log_signal(cond)); - const char *assume_attr = nullptr; // inst->GetAttValue("assume"); - - Cell *cell = nullptr; - if (assume_attr != nullptr && !strcmp(assume_attr, "1")) - cell = module->addAssume(new_verific_id(inst), cond, State::S1); - else - cell = module->addAssert(new_verific_id(inst), cond, State::S1); - + Cell *cell = module->addAssert(new_verific_id(inst), cond, State::S1); import_attributes(cell->attributes, inst); continue; } @@ -2182,7 +2205,8 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma if (is_blackbox(inst->View())) { FOREACH_PARAMETER_OF_INST(inst, mi2, param_name, param_value) { const TypeRange *tr = inst->View()->GetTypeRange(param_name) ; - cell->setParam(RTLIL::escape_id(param_name), verific_const(tr->GetTypeName(), param_value, inst->View())); + const char* type_name = (tr) ? tr->GetTypeName() : nullptr; + cell->setParam(RTLIL::escape_id(param_name), verific_const(type_name, param_value, inst->View())); } } @@ -2282,7 +2306,7 @@ void VerificImporter::import_netlist(RTLIL::Design *design, Netlist *nl, std::ma continue; if (non_ff_bits.count(SigBit(wire, i))) - initval[i] = State::Sx; + initval.bits()[i] = State::Sx; } if (wire->port_input) { @@ -2469,7 +2493,7 @@ Cell *VerificClocking::addDff(IdString name, SigSpec sig_d, SigSpec sig_q, Const if (c.wire && c.wire->attributes.count(ID::init)) { Const val = c.wire->attributes.at(ID::init); for (int i = 0; i < GetSize(c); i++) - initval[offset+i] = val[c.offset+i]; + initval.bits()[offset+i] = val[c.offset+i]; } offset += GetSize(c); } @@ -2540,7 +2564,7 @@ Cell *VerificClocking::addAldff(IdString name, RTLIL::SigSpec sig_aload, RTLIL:: if (c.wire && c.wire->attributes.count(ID::init)) { Const val = c.wire->attributes.at(ID::init); for (int i = 0; i < GetSize(c); i++) - initval[offset+i] = val[c.offset+i]; + initval.bits()[offset+i] = val[c.offset+i]; } offset += GetSize(c); } @@ -2697,11 +2721,51 @@ struct VerificExtNets } }; +#ifdef VERIFIC_SYSTEMVERILOG_SUPPORT +static msg_type_t prev_1063; +#endif +#ifdef VERIFIC_VHDL_SUPPORT +static msg_type_t prev_1240 ; +static msg_type_t prev_1241 ; +#endif +void save_blackbox_msg_state() +{ +#ifdef VERIFIC_SYSTEMVERILOG_SUPPORT + prev_1063 = Message::GetMessageType("VERI-1063") ; + Message::SetMessageType("VERI-1063", VERIFIC_INFO); +#endif +#ifdef VERIFIC_VHDL_SUPPORT + prev_1240 = Message::GetMessageType("VHDL-1240") ; + prev_1241 = Message::GetMessageType("VHDL-1241") ; + Message::SetMessageType("VHDL-1240", VERIFIC_INFO); + Message::SetMessageType("VHDL-1241", VERIFIC_INFO); +#endif +} + +void restore_blackbox_msg_state() +{ +#ifdef VERIFIC_SYSTEMVERILOG_SUPPORT + Message::ClearMessageType("VERI-1063") ; + if (Message::GetMessageType("VERI-1063")!=prev_1063) + Message::SetMessageType("VERI-1063", prev_1063); +#endif +#ifdef VERIFIC_VHDL_SUPPORT + Message::ClearMessageType("VHDL-1240") ; + Message::ClearMessageType("VHDL-1241") ; + if (Message::GetMessageType("VHDL-1240")!=prev_1240) + Message::SetMessageType("VHDL-1240", prev_1240); + if (Message::GetMessageType("VHDL-1241")!=prev_1241) + Message::SetMessageType("VHDL-1241", prev_1241); +#endif +} + void import_all(const char* work, std::map *nl_todo, Map *parameters, bool show_message, std::string ppfile YS_MAYBE_UNUSED) { #ifdef YOSYSHQ_VERIFIC_EXTENSIONS + save_blackbox_msg_state(); VerificExtensions::ElaborateAndRewrite(work, parameters); verific_error_msg.clear(); + restore_blackbox_msg_state(); #endif #ifdef VERIFIC_SYSTEMVERILOG_SUPPORT if (!ppfile.empty()) @@ -2832,8 +2896,10 @@ std::set import_tops(const char* work, std::map import_tops(const char* work, std::mapSetCompileAsBlackbox(); } } - Message::ClearMessageType("VHDL-1240") ; - Message::ClearMessageType("VHDL-1241") ; - if (Message::GetMessageType("VHDL-1240")!=prev_1240) - Message::SetMessageType("VHDL-1240", prev_1240); - if (Message::GetMessageType("VHDL-1241")!=prev_1241) - Message::SetMessageType("VHDL-1241", prev_1241); - + restore_blackbox_msg_state(); } #endif - msg_type_t prev_1063; #ifdef VERIFIC_SYSTEMVERILOG_SUPPORT void add_modules_to_map(Map &map, std::string work, bool flag_lib) { @@ -3358,9 +3415,7 @@ struct VerificPass : public Pass { map.Insert(veri_module,veri_module); } } - - prev_1063 = Message::GetMessageType("VERI-1063") ; - Message::SetMessageType("VERI-1063", VERIFIC_INFO); + save_blackbox_msg_state(); } void set_modules_to_blackbox(Map &map, std::string work, bool flag_lib) @@ -3375,15 +3430,12 @@ struct VerificPass : public Pass { veri_module->SetCompileAsBlackbox(); } } - Message::ClearMessageType("VERI-1063") ; - if (Message::GetMessageType("VERI-1063")!=prev_1063) - Message::SetMessageType("VERI-1063", prev_1063); + restore_blackbox_msg_state(); } #endif void execute(std::vector args, RTLIL::Design *design) override { - static bool set_verific_global_flags = true; if (check_noverific_env()) log_cmd_error("This version of Yosys is built without Verific support.\n" @@ -3416,11 +3468,13 @@ struct VerificPass : public Pass { RuntimeFlags::SetVar("veri_extract_dualport_rams", 0); RuntimeFlags::SetVar("veri_extract_multiport_rams", 1); RuntimeFlags::SetVar("veri_allow_any_ram_in_loop", 1); + RuntimeFlags::SetVar("veri_replace_const_exprs", 1); #endif #ifdef VERIFIC_VHDL_SUPPORT RuntimeFlags::SetVar("vhdl_extract_dualport_rams", 0); RuntimeFlags::SetVar("vhdl_extract_multiport_rams", 1); RuntimeFlags::SetVar("vhdl_allow_any_ram_in_loop", 1); + RuntimeFlags::SetVar("vhdl_replace_const_exprs", 1); RuntimeFlags::SetVar("vhdl_support_variable_slice", 1); RuntimeFlags::SetVar("vhdl_ignore_assertion_statements", 0); @@ -3440,6 +3494,14 @@ struct VerificPass : public Pass { // WARNING: instantiating unknown module 'XYZ' (VERI-1063) Message::SetMessageType("VERI-1063", VERIFIC_ERROR); + // Downgrade warnings about things that are normal + // VERIFIC-WARNING [VERI-1209] foo.sv:98: expression size 7 truncated to fit in target size 6 + Message::SetMessageType("VERI-1209", VERIFIC_INFO); + // VERIFIC-WARNING [VERI-1142] foo.sv:55: system task 'display' is ignored for synthesis + Message::SetMessageType("VERI-1142", VERIFIC_INFO); + // VERIFIC-WARNING [VERI-2418] foo.svh:503: parameter 'all_cfgs_gp' declared inside package 'bp_common_pkg' shall be treated as localparam + Message::SetMessageType("VERI-2418", VERIFIC_INFO); + // https://github.com/YosysHQ/yosys/issues/1055 RuntimeFlags::SetVar("veri_elaborate_top_level_modules_having_interface_ports", 1) ; #endif @@ -3498,6 +3560,9 @@ struct VerificPass : public Pass { } else if (Strings::compare(args[argidx].c_str(), "warnings")) { Message::SetAllMessageType(VERIFIC_WARNING, new_type); } else if (Strings::compare(args[argidx].c_str(), "infos")) { + Message::SetMessageType("VERI-1209", new_type); + Message::SetMessageType("VERI-1142", new_type); + Message::SetMessageType("VERI-2418", new_type); Message::SetAllMessageType(VERIFIC_INFO, new_type); } else if (Strings::compare(args[argidx].c_str(), "comments")) { Message::SetAllMessageType(VERIFIC_COMMENT, new_type); @@ -4062,6 +4127,12 @@ struct VerificPass : public Pass { if (argidx > GetSize(args) && args[argidx].compare(0, 1, "-") == 0) cmd_error(args, argidx, "unknown option"); + if ((unsigned long)verific_sva_fsm_limit >= sizeof(1ull)*8) + log_cmd_error("-L %d: limit too large; maximum allowed value is %zu.\n", verific_sva_fsm_limit, sizeof(1ull)*8-1); + + if (already_imported) + log_warning("Note that all Verific flags were reset to defaults after last -import.\n"); + std::set top_mod_names; if (mode_all) @@ -4139,6 +4210,7 @@ struct VerificPass : public Pass { } verific_cleanup(); + already_imported = true; goto check_error; } @@ -4189,7 +4261,7 @@ struct VerificPass : public Pass { } if (v[0] == '"') { std::string s = v.substr(1, GetSize(v)-2); - RuntimeFlags::SetStringVar(k.c_str(), v.c_str()); + RuntimeFlags::SetStringVar(k.c_str(), s.c_str()); goto check_error; } char *endptr; @@ -4274,7 +4346,7 @@ struct ReadPass : public Pass { log("\n"); log(" read {-f|-F} \n"); log("\n"); - log("Load and execute the specified command file. (Requires Verific.)\n"); + log("Load and execute the specified command file.\n"); log("Check verific command for more information about supported commands in file.\n"); log("\n"); log("\n"); @@ -4388,10 +4460,14 @@ struct ReadPass : public Pass { if (args[1] == "-f" || args[1] == "-F") { if (use_verific) { args[0] = "verific"; - Pass::call(design, args); } else { - cmd_error(args, 1, "This version of Yosys is built without Verific support.\n"); +#if !defined(__wasm) + args[0] = "read_verilog_file_list"; +#else + cmd_error(args, 1, "Command files are not supported on this platform.\n"); +#endif } + Pass::call(design, args); return; } diff --git a/frontends/verific/verific.h b/frontends/verific/verific.h index 0b9616e19..4e9c7a305 100644 --- a/frontends/verific/verific.h +++ b/frontends/verific/verific.h @@ -71,7 +71,7 @@ struct VerificImporter std::map net_map; std::map sva_posedge_map; - pool any_all_nets; + pool any_all_nets; bool mode_gates, mode_keep, mode_nosva, mode_names, mode_verific; bool mode_autocover, mode_fullinit; @@ -81,7 +81,7 @@ struct VerificImporter RTLIL::SigBit net_map_at(Verific::Net *net); RTLIL::IdString new_verific_id(Verific::DesignObj *obj); - void import_attributes(dict &attributes, Verific::DesignObj *obj, Verific::Netlist *nl = nullptr); + void import_attributes(dict &attributes, Verific::DesignObj *obj, Verific::Netlist *nl = nullptr, int wire_width_hint = -1); RTLIL::SigBit netToSigBit(Verific::Net *net); RTLIL::SigSpec operatorInput(Verific::Instance *inst); @@ -89,7 +89,7 @@ struct VerificImporter RTLIL::SigSpec operatorInput2(Verific::Instance *inst); RTLIL::SigSpec operatorInport(Verific::Instance *inst, const char *portname); RTLIL::SigSpec operatorInportCase(Verific::Instance *inst, const char *portname); - RTLIL::SigSpec operatorOutput(Verific::Instance *inst, const pool *any_all_nets = nullptr); + RTLIL::SigSpec operatorOutput(Verific::Instance *inst, const pool *any_all_nets = nullptr); bool import_netlist_instance_gates(Verific::Instance *inst, RTLIL::IdString inst_name); bool import_netlist_instance_cells(Verific::Instance *inst, RTLIL::IdString inst_name); diff --git a/frontends/verific/verificsva.cc b/frontends/verific/verificsva.cc index b219c0165..6e87bd267 100644 --- a/frontends/verific/verificsva.cc +++ b/frontends/verific/verificsva.cc @@ -479,14 +479,14 @@ struct SvaFsm GetSize(dnode.ctrl), verific_sva_fsm_limit); } - for (int i = 0; i < (1 << GetSize(dnode.ctrl)); i++) + for (unsigned long long i = 0; i < (1ull << GetSize(dnode.ctrl)); i++) { Const ctrl_val(i, GetSize(dnode.ctrl)); pool ctrl_bits; - for (int i = 0; i < GetSize(dnode.ctrl); i++) - if (ctrl_val[i] == State::S1) - ctrl_bits.insert(dnode.ctrl[i]); + for (int j = 0; j < GetSize(dnode.ctrl); j++) + if (ctrl_val[j] == State::S1) + ctrl_bits.insert(dnode.ctrl[j]); vector new_state; bool accept = false, cond = false; @@ -575,7 +575,7 @@ struct SvaFsm if (delta_pos >= 0 && i_within_j && j_within_i) { did_something = true; - values[i][delta_pos] = State::Sa; + values[i].bits()[delta_pos] = State::Sa; values[j] = values.back(); values.pop_back(); goto next_pair; @@ -1051,7 +1051,7 @@ struct VerificSvaImporter msg.c_str(), inst->View()->Owner()->Name(), inst->Name()), inst->Linefile()); } - dict check_expression_cache; + dict check_expression_cache; bool check_expression(Net *net, bool raise_error = false) { @@ -1613,7 +1613,10 @@ struct VerificSvaImporter } else if (inst->Type() == PRIM_SVA_OVERLAPPED_IMPLICATION || - inst->Type() == PRIM_SVA_NON_OVERLAPPED_IMPLICATION) + inst->Type() == PRIM_SVA_NON_OVERLAPPED_IMPLICATION || + (mode_cover && ( + inst->Type() == PRIM_SVA_OVERLAPPED_FOLLOWED_BY || + inst->Type() == PRIM_SVA_NON_OVERLAPPED_IMPLICATION))) { Net *antecedent_net = inst->GetInput1(); Net *consequent_net = inst->GetInput2(); @@ -1621,7 +1624,7 @@ struct VerificSvaImporter SvaFsm antecedent_fsm(clocking, trig); node = parse_sequence(antecedent_fsm, antecedent_fsm.createStartNode(), antecedent_net); - if (inst->Type() == PRIM_SVA_NON_OVERLAPPED_IMPLICATION) { + if (inst->Type() == PRIM_SVA_NON_OVERLAPPED_IMPLICATION || inst->Type() == PRIM_SVA_NON_OVERLAPPED_FOLLOWED_BY) { int next_node = antecedent_fsm.createNode(); antecedent_fsm.createEdge(node, next_node); node = next_node; diff --git a/frontends/verilog/verilog_frontend.cc b/frontends/verilog/verilog_frontend.cc index d363d71fb..1f272ca4f 100644 --- a/frontends/verilog/verilog_frontend.cc +++ b/frontends/verilog/verilog_frontend.cc @@ -26,6 +26,10 @@ * */ +#if !defined(__wasm) +#include +#endif + #include "verilog_frontend.h" #include "preproc.h" #include "kernel/yosys.h" @@ -672,6 +676,89 @@ struct VerilogDefines : public Pass { } } VerilogDefines; +#if !defined(__wasm) + +static void parse_file_list(const std::string &file_list_path, RTLIL::Design *design, bool relative_to_file_list_path) +{ + std::ifstream flist(file_list_path); + if (!flist.is_open()) { + log_error("Verilog file list file does not exist"); + exit(1); + } + + std::filesystem::path file_list_parent_dir = std::filesystem::path(file_list_path).parent_path(); + + std::string v_file_name; + while (std::getline(flist, v_file_name)) { + if (v_file_name.empty()) { + continue; + } + + std::filesystem::path verilog_file_path; + if (relative_to_file_list_path) { + verilog_file_path = file_list_parent_dir / v_file_name; + } else { + verilog_file_path = std::filesystem::current_path() / v_file_name; + } + + bool is_sv = (verilog_file_path.extension() == ".sv"); + + std::vector read_verilog_cmd = {"read_verilog", "-defer"}; + if (is_sv) { + read_verilog_cmd.push_back("-sv"); + } + read_verilog_cmd.push_back(verilog_file_path.string()); + Pass::call(design, read_verilog_cmd); + } + + flist.close(); +} + +struct VerilogFileList : public Pass { + VerilogFileList() : Pass("read_verilog_file_list", "parse a Verilog file list") {} + void help() override + { + // |---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---|---v---| + log("\n"); + log(" read_verilog_file_list [options]\n"); + log("\n"); + log("Parse a Verilog file list, and pass the list of Verilog files to read_verilog\n"); + log("command\n"); + log("\n"); + log(" -F file_list_path\n"); + log(" File list file contains list of Verilog files to be parsed, any path is\n"); + log(" treated relative to the file list file\n"); + log("\n"); + log(" -f file_list_path\n"); + log(" File list file contains list of Verilog files to be parsed, any path is\n"); + log(" treated relative to current working directroy\n"); + log("\n"); + } + + void execute(std::vector args, RTLIL::Design *design) override + { + size_t argidx; + for (argidx = 1; argidx < args.size(); argidx++) { + std::string arg = args[argidx]; + if (arg == "-F" && argidx + 1 < args.size()) { + std::string file_list_path = args[++argidx]; + parse_file_list(file_list_path, design, true); + continue; + } + if (arg == "-f" && argidx + 1 < args.size()) { + std::string file_list_path = args[++argidx]; + parse_file_list(file_list_path, design, false); + continue; + } + break; + } + + extra_args(args, argidx, design, false); + } +} VerilogFilelist; + +#endif + YOSYS_NAMESPACE_END // the yyerror function used by bison to report parser errors diff --git a/frontends/verilog/verilog_lexer.l b/frontends/verilog/verilog_lexer.l index 8a3734302..e2d7a2cd9 100644 --- a/frontends/verilog/verilog_lexer.l +++ b/frontends/verilog/verilog_lexer.l @@ -112,6 +112,129 @@ static bool isUserType(std::string &s) return false; } +static bool is_hex_dig(char c, int *val) +{ + if ('0' <= c && c <= '9') { + *val = c - '0'; + return true; + } else if ('a' <= c && c <= 'f') { + *val = c - 'a' + 0xA; + return true; + } else if ('A' <= c && c <= 'F') { + *val = c - 'A' + 0xA; + return true; + } else if (c == 'x' || c == 'X' || c == 'z' || c == 'Z' || c == '?') { + log_file_warning(AST::current_filename.c_str(), frontend_verilog_yyget_lineno(), "'%c' not a valid digit in hex escape sequence.\n", c); + *val = 0; // not semantically valid in hex escape... + return true; // ...but still processed as part of hex token + } + + return false; +} + +static bool is_oct_dig(char c, int *val) +{ + if ('0' <= c && c <= '7') { + *val = c - '0'; + return true; + } else if (c == 'x' || c == 'X' || c == 'z' || c == 'Z' || c == '?') { + log_file_warning(AST::current_filename.c_str(), frontend_verilog_yyget_lineno(), "'%c' not a valid digit in octal escape sequence.\n", c); + *val = 0; // not semantically valid in octal escape... + return true; // ...but still processed as part of octal token + } + + return false; +} + +static std::string *process_str(char *str, int len, bool triple) +{ + char *in, *out; // Overwrite input buffer: flex manual states "Actions + // are free to modify 'yytext' except for lengthening it". + + for (in = str, out = str; in < str + len; in++) + switch (*in) { + case '\n': + case '\r': + if (in + 1 < str + len && (in[1] ^ *in) == ('\n' ^ '\r')) + in++; + if (!triple) + log_file_warning(AST::current_filename.c_str(), frontend_verilog_yyget_lineno(), "Multi-line string literals should be triple-quoted or escaped.\n"); + *out++ = '\n'; + break; + case '\\': + in++; + log_assert(in < str + len); + switch (*in) { + case 'a': + *out++ = '\a'; + break; + case 'f': + *out++ = '\f'; + break; + case 'n': + *out++ = '\n'; + break; + case 'r': /* not part of IEEE-1800 2023, but seems + like a good idea to support it anyway */ + *out++ = '\r'; + break; + case 't': + *out++ = '\t'; + break; + case 'v': + *out++ = '\v'; + break; + case 'x': + int val; + if (in + 1 < str + len && is_hex_dig(in[1], &val)) { + *out = val; + in++; + if (in + 1 < str + len && is_hex_dig(in[1], &val)) { + *out = *out * 0x10 + val; + in++; + } + out++; + } else + log_file_warning(AST::current_filename.c_str(), frontend_verilog_yyget_lineno(), "ignoring invalid hex escape.\n"); + break; + case '\\': + *out++ = '\\'; + break; + case '"': + *out++ = '"'; + break; + case '\n': + case '\r': + if (in + 1 < str + len && (in[1] ^ *in) == ('\n' ^ '\r')) + in++; + break; + default: + if ('0' <= *in && *in <= '7') { + int val; + + *out = *in - '0'; + if (in + 1 < str + len && is_oct_dig(in[1], &val)) { + *out = *out * 010 + val; + in++; + if (in + 1 < str + len && is_oct_dig(in[1], &val)) { + if (*out >= 040) + log_file_warning(AST::current_filename.c_str(), frontend_verilog_yyget_lineno(), "octal escape exceeds \\377\n"); + *out = *out * 010 + val; + in++; + } + } + out++; + } else + *out++ = *in; + } + break; + default: + *out++ = *in; + } + + return new std::string(str, out - str); +} + %} %option yylineno @@ -122,7 +245,6 @@ static bool isUserType(std::string &s) %option prefix="frontend_verilog_yy" %x COMMENT -%x STRING %x SYNOPSYS_TRANSLATE_OFF %x SYNOPSYS_FLAGS %x IMPORT_DPI @@ -335,48 +457,9 @@ TIME_SCALE_SUFFIX [munpf]?s return TOK_REALVAL; } -\" { BEGIN(STRING); } -\\. { yymore(); real_location = old_location; } -\" { - BEGIN(0); - char *yystr = strdup(yytext); - yystr[strlen(yytext) - 1] = 0; - int i = 0, j = 0; - while (yystr[i]) { - if (yystr[i] == '\\' && yystr[i + 1]) { - i++; - if (yystr[i] == 'a') - yystr[i] = '\a'; - else if (yystr[i] == 'f') - yystr[i] = '\f'; - else if (yystr[i] == 'n') - yystr[i] = '\n'; - else if (yystr[i] == 'r') - yystr[i] = '\r'; - else if (yystr[i] == 't') - yystr[i] = '\t'; - else if (yystr[i] == 'v') - yystr[i] = '\v'; - else if ('0' <= yystr[i] && yystr[i] <= '7') { - yystr[i] = yystr[i] - '0'; - if ('0' <= yystr[i + 1] && yystr[i + 1] <= '7') { - yystr[i + 1] = yystr[i] * 8 + yystr[i + 1] - '0'; - i++; - } - if ('0' <= yystr[i + 1] && yystr[i + 1] <= '7') { - yystr[i + 1] = yystr[i] * 8 + yystr[i + 1] - '0'; - i++; - } - } - } - yystr[j++] = yystr[i++]; - } - yystr[j] = 0; - yylval->string = new std::string(yystr, j); - free(yystr); - return TOK_STRING; -} -. { yymore(); real_location = old_location; } +\"([^\\"]|\\.|\\\n)*\" { yylval->string = process_str(yytext + 1, yyleng - 2, false); return TOK_STRING; } + +\"{3}(\"{0,2}([^\\"]|\\.|\\\n))*\"{3} { yylval->string = process_str(yytext + 3, yyleng - 6, true); return TOK_STRING; } and|nand|or|nor|xor|xnor|not|buf|bufif0|bufif1|notif0|notif1 { yylval->string = new std::string(yytext); diff --git a/frontends/verilog/verilog_parser.y b/frontends/verilog/verilog_parser.y index 15a04eb28..17edc357d 100644 --- a/frontends/verilog/verilog_parser.y +++ b/frontends/verilog/verilog_parser.y @@ -336,7 +336,8 @@ static AstNode *addIncOrDecExpr(AstNode *lhs, dict *attr, AS log_assert(stmt->type == AST_ASSIGN_EQ); AstNode *expr = stmt->children[0]->clone(); if (undo) { - AstNode *minus_one = AstNode::mkconst_int(-1, true, 1); + AstNode *one = AstNode::mkconst_int(1, false, 1); + AstNode *minus_one = new AstNode(AST_NEG, one); expr = new AstNode(op, expr, minus_one); } SET_AST_NODE_LOC(expr, begin, end); @@ -426,7 +427,7 @@ static const AstNode *addAsgnBinopStmt(dict *attr, AstNode * %type opt_property always_comb_or_latch always_or_always_ff %type opt_signedness_default_signed opt_signedness_default_unsigned %type integer_atom_type integer_vector_type -%type attr case_attr +%type attr if_attr case_attr %type struct_union %type asgn_binop inc_or_dec_op %type genvar_identifier @@ -464,6 +465,7 @@ static const AstNode *addAsgnBinopStmt(dict *attr, AstNode * %% input: { + (void)frontend_verilog_yynerrs; ast_stack.clear(); ast_stack.push_back(current_ast); } design { @@ -1854,7 +1856,7 @@ struct_decl: } ; -struct_type: struct_union { astbuf2 = $1; } struct_body { $$ = astbuf2; } +struct_type: struct_union { astbuf2 = $1; astbuf2->is_custom_type = true; } struct_body { $$ = astbuf2; } ; struct_union: @@ -2248,7 +2250,8 @@ cell_parameter: node->children.push_back($1); } | '.' TOK_ID '(' ')' { - // just ignore empty parameters + // delete unused TOK_ID + delete $2; } | '.' TOK_ID '(' expr ')' { AstNode *node = new AstNode(AST_PARASET); @@ -2869,17 +2872,38 @@ behavioral_stmt: ast_stack.pop_back(); ast_stack.pop_back(); } | - attr TOK_IF '(' expr ')' { - AstNode *node = new AstNode(AST_CASE); + if_attr TOK_IF '(' expr ')' { + AstNode *node = 0; AstNode *block = new AstNode(AST_BLOCK); - AstNode *cond = new AstNode(AST_COND, AstNode::mkconst_int(1, false, 1), block); + AstNode *context = ast_stack.back(); + if (context && context->type == AST_BLOCK && context->get_bool_attribute(ID::promoted_if)) { + AstNode *outer = ast_stack[ast_stack.size() - 2]; + log_assert (outer && outer->type == AST_CASE); + if (outer->get_bool_attribute(ID::parallel_case)) { + // parallel "else if": append condition to outer "if" + node = outer; + log_assert (node->children.size()); + ast_stack.pop_back(); + delete node->children.back(); + node->children.pop_back(); + ast_stack.push_back(block); + } else if (outer->get_bool_attribute(ID::full_case)) + (*$1)[ID::full_case] = AstNode::mkconst_int(1, false); + } + AstNode *expr = new AstNode(AST_REDUCE_BOOL, $4); + if (!node) { + // not parallel "else if": begin new construction + node = new AstNode(AST_CASE); + append_attr(node, $1); + ast_stack.back()->children.push_back(node); + node->children.push_back(node->get_bool_attribute(ID::parallel_case) ? AstNode::mkconst_int(1, false, 1) : expr); + } else + free_attr($1); + AstNode *cond = new AstNode(AST_COND, node->get_bool_attribute(ID::parallel_case) ? expr : AstNode::mkconst_int(1, false, 1), block); SET_AST_NODE_LOC(cond, @4, @4); - ast_stack.back()->children.push_back(node); - node->children.push_back(new AstNode(AST_REDUCE_BOOL, $4)); node->children.push_back(cond); ast_stack.push_back(node); ast_stack.push_back(block); - append_attr(node, $1); } behavioral_stmt { SET_AST_NODE_LOC(ast_stack.back(), @7, @7); } optional_else { @@ -2899,6 +2923,33 @@ behavioral_stmt: ast_stack.pop_back(); }; +if_attr: + attr { + $$ = $1; + } | + attr TOK_UNIQUE0 { + AstNode *context = ast_stack.back(); + if (context && context->type == AST_BLOCK && context->get_bool_attribute(ID::promoted_if)) + frontend_verilog_yyerror("unique0 keyword cannot be used for 'else if' branch."); + (*$1)[ID::parallel_case] = AstNode::mkconst_int(1, false); + $$ = $1; + } | + attr TOK_PRIORITY { + AstNode *context = ast_stack.back(); + if (context && context->type == AST_BLOCK && context->get_bool_attribute(ID::promoted_if)) + frontend_verilog_yyerror("priority keyword cannot be used for 'else if' branch."); + (*$1)[ID::full_case] = AstNode::mkconst_int(1, false); + $$ = $1; + } | + attr TOK_UNIQUE { + AstNode *context = ast_stack.back(); + if (context && context->type == AST_BLOCK && context->get_bool_attribute(ID::promoted_if)) + frontend_verilog_yyerror("unique keyword cannot be used for 'else if' branch."); + (*$1)[ID::full_case] = AstNode::mkconst_int(1, false); + (*$1)[ID::parallel_case] = AstNode::mkconst_int(1, false); + $$ = $1; + }; + case_attr: attr { $$ = $1; @@ -2946,6 +2997,7 @@ behavioral_stmt_list: optional_else: TOK_ELSE { AstNode *block = new AstNode(AST_BLOCK); + block->attributes[ID::promoted_if] = AstNode::mkconst_int(1, false ); AstNode *cond = new AstNode(AST_COND, new AstNode(AST_DEFAULT), block); SET_AST_NODE_LOC(cond, @1, @1); @@ -3506,6 +3558,12 @@ basic_expr: $$ = new AstNode(AST_CAST_SIZE, $1, $4); SET_AST_NODE_LOC($$, @1, @4); } | + typedef_base_type OP_CAST '(' expr ')' { + if (!sv_mode) + frontend_verilog_yyerror("Static cast is only supported in SystemVerilog mode."); + $$ = new AstNode(AST_CAST_SIZE, $1, $4); + SET_AST_NODE_LOC($$, @1, @4); + } | '(' expr '=' expr ')' { ensureAsgnExprAllowed(); AstNode *node = new AstNode(AST_ASSIGN_EQ, $2, $4); diff --git a/guidelines/Checklists b/guidelines/Checklists deleted file mode 100644 index 75af12fa9..000000000 --- a/guidelines/Checklists +++ /dev/null @@ -1,116 +0,0 @@ -Checklist for adding internal cell types -======================================== - -Things to do right away: - - - Add to kernel/celltypes.h (incl. eval() handling for non-mem cells) - - Add to InternalCellChecker::check() in kernel/rtlil.cc - - Add to techlibs/common/simlib.v - - Add to techlibs/common/techmap.v - -Things to do after finalizing the cell interface: - - - Add support to kernel/satgen.h for the new cell type - - Add to docs/source/CHAPTER_CellLib.rst (or just add a fixme to the bottom) - - Maybe add support to the Verilog backend for dumping such cells as expression - - - -Checklist for creating Yosys releases -===================================== - -Update the CHANGELOG file: - - cd ~yosys - gitk & - vi CHANGELOG - - -Update and check documentation: - - cd ~yosys - make docs - - sanity check the figures in docs/images - - if there are any odd things -> investigate - - cd ~yosys - vi README guidelines/* - - is the information provided in those file still up to date - - -Then with default config setting: - - cd ~yosys - make vgtest - - cd ~yosys - ./yosys -p 'proc; show' tests/simple/fiedler-cooley.v - ./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v - ./yosys -p 'synth; show' tests/simple/fiedler-cooley.v - ./yosys -p 'synth_xilinx -top up3down5; show' tests/simple/fiedler-cooley.v - - cd ~yosys/examples/cmos - bash testbench.sh - - cd ~yosys/examples/basys3 - bash run.sh - - -Test building plugins with various of the standard passes: - - yosys-config --build test.so equiv_simple.cc - - also check the code examples in guidelines/GettingStarted - - -And if a version of the verific library is currently available: - - cd ~yosys - cat frontends/verific/build_amd64.txt - - follow instructions - - cd frontends/verific - ../../yosys test_navre.ys - - -Finally run all tests with "make config-{clang,gcc}": - - cd ~yosys - make clean - make test - make ystests - make vloghtb - make install - - cd ~yosys-bigsim - make clean - make full - - cd ~vloghammer - make purge gen_issues gen_samples - make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" REPORT_FULL=1 world - chromium-browser report.html - - -Release: - - - set YOSYS_VER to x.y.z in Makefile - - remove "bumpversion" target from Makefile - - update version string in CHANGELOG - git commit -am "Yosys x.y.z" - - - push tag to github - - post changelog on github - - post short release note on reddit - - -Updating the website: - - cd ~yosys - make install - - cd ~yosys-web - make update_show - git commit -am update - make push - - - Read the Docs updates handled by Jenkins on source change diff --git a/guidelines/CodeOfConduct b/guidelines/CodeOfConduct deleted file mode 100644 index 92decd3b6..000000000 --- a/guidelines/CodeOfConduct +++ /dev/null @@ -1,72 +0,0 @@ -Contributor Covenant Code of Conduct - -Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or - advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at contact@yosyshq.com and/or -claire@clairexen.net. All complaints will be reviewed and investigated and -will result in a response that is deemed necessary and appropriate to the -circumstances. The project team is obligated to maintain confidentiality with -regard to the reporter of an incident. Further details of specific enforcement -policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -Attribution - -This Code of Conduct is adapted from the Contributor Covenant, version 1.4, -available at http://contributor-covenant.org/version/1/4/ diff --git a/guidelines/CodingStyle b/guidelines/CodingStyle deleted file mode 100644 index 491507cdd..000000000 --- a/guidelines/CodingStyle +++ /dev/null @@ -1,34 +0,0 @@ -Coding Style -============ - - -Formatting of code ------------------- - -- Yosys code is using tabs for indentation. Tabs are 8 characters. - -- A continuation of a statement in the following line is indented by - two additional tabs. - -- Lines are as long as you want them to be. A good rule of thumb is - to break lines at about column 150. - -- Opening braces can be put on the same or next line as the statement - opening the block (if, switch, for, while, do). Put the opening brace - on its own line for larger blocks, especially blocks that contains - blank lines. - -- Otherwise stick to the Linux Kernel Coding Style: - https://www.kernel.org/doc/Documentation/process/coding-style.rst - - -C++ Language -------------- - -Yosys is written in C++17. - -In general Yosys uses "int" instead of "size_t". To avoid compiler -warnings for implicit type casts, always use "GetSize(foobar)" instead -of "foobar.size()". (GetSize() is defined in kernel/yosys.h) - -Use range-based for loops whenever applicable. \ No newline at end of file diff --git a/guidelines/GettingStarted b/guidelines/GettingStarted index 110f63185..17fe32523 100644 --- a/guidelines/GettingStarted +++ b/guidelines/GettingStarted @@ -37,57 +37,15 @@ And then executed using the following command: Yosys Data Structures --------------------- -Here is a short list of data structures that you should make yourself familiar -with before you write C++ code for Yosys. The following data structures are all -defined when "kernel/yosys.h" is included and USING_YOSYS_NAMESPACE is used. + 1. Container classes based on hashing - 1. Yosys Container Classes +Yosys heavily relies on custom container data structures such as dict or pool +defined in kernel/hashlib.h. +dict is essentially a replacement for std::unordered_map +and pool is a replacement for std::unordered_set. Please refer to +docs/source/yosys_internals/hashing.rst for more information on those. -Yosys uses dict and pool as main container classes. dict is -essentially a replacement for std::unordered_map and pool is a -replacement for std::unordered_set. The main characteristics are: - - - dict and pool are about 2x faster than the std containers - - - references to elements in a dict or pool are invalidated by - insert and remove operations (similar to std::vector on push_back()). - - - some iterators are invalidated by erase(). specifically, iterators - that have not passed the erased element yet are invalidated. (erase() - itself returns valid iterator to the next element.) - - - no iterators are invalidated by insert(). elements are inserted at - begin(). i.e. only a new iterator that starts at begin() will see the - inserted elements. - - - the method .count(key, iterator) is like .count(key) but only - considers elements that can be reached via the iterator. - - - iterators can be compared. it1 < it2 means that the position of t2 - can be reached via t1 but not vice versa. - - - the method .sort() can be used to sort the elements in the container - the container stays sorted until elements are added or removed. - - - dict and pool will have the same order of iteration across - all compilers, standard libraries and architectures. - -In addition to dict and pool there is also an idict that -creates a bijective map from K to the integers. For example: - - idict si; - log("%d\n", si("hello")); // will print 42 - log("%d\n", si("world")); // will print 43 - log("%d\n", si.at("world")); // will print 43 - log("%d\n", si.at("dummy")); // will throw exception - log("%s\n", si[42].c_str())); // will print hello - log("%s\n", si[43].c_str())); // will print world - log("%s\n", si[44].c_str())); // will throw exception - -It is not possible to remove elements from an idict. - -Finally mfp implements a merge-find set data structure (aka. disjoint-set or -union-find) over the type K ("mfp" = merge-find-promote). +Otherwise, Yosys makes use of the following: 2. Standard STL data types diff --git a/guidelines/UnitTests b/guidelines/UnitTests deleted file mode 100644 index d42a63ce5..000000000 --- a/guidelines/UnitTests +++ /dev/null @@ -1,69 +0,0 @@ -How to add unit test -==================== - -Unit test brings some advantages, briefly, we can list some of them (reference -[1](https://en.wikipedia.org/wiki/Unit_testing)): - -* Tests reduce bugs in new features; -* Tests reduce bugs in existing features; -* Tests are good documentation; -* Tests reduce the cost of change; -* Tests allow refactoring; - -With those advantages in mind, it was required to choose a framework which fits -well with C/C++ code. Hence, it was chosen (google test) -[https://github.com/google/googletest], because it is largely used and it is -relatively easy learn. - -Install and configure google test (manually) --------------------------------------------- - -In this section, you will see a brief description of how to install google -test. However, it is strongly recommended that you take a look to the official -repository (https://github.com/google/googletest) and refers to that if you -have any problem to install it. Follow the steps below: - -* Install: cmake and pthread -* Clone google test project from: https://github.com/google/googletest and - enter in the project directory -* Inside project directory, type: - -``` -cmake -DBUILD_SHARED_LIBS=ON . -make -``` - -* After compilation, copy all "*.so" inside directory "googlemock" and - "googlemock/gtest" to "/usr/lib/" -* Done! Now you can compile your tests. - -If you have any problem, go to the official repository to find help. - -Ps.: Some distros already have googletest packed. If your distro supports it, -you can use it instead of compile. - -Create new unit test --------------------- - -If you want to add new unit tests for Yosys, just follow the steps below: - -* Go to directory "yosys/test/unit/" -* In this directory you can find something similar Yosys's directory structure. - To create your unit test file you have to follow this pattern: - fileNameToImplementUnitTest + Test.cc. E.g.: if you want to implement the - unit test for kernel/celledges.cc, you will need to create a file like this: - tests/unit/kernel/celledgesTest.cc; -* Implement your unit test - -Run unit test -------------- - -To compile and run all unit tests, just go to yosys root directory and type: -``` -make unit-test -``` - -If you want to remove all unit test files, type: -``` -make clean-unit-test -``` diff --git a/guidelines/Windows b/guidelines/Windows deleted file mode 100644 index c4548c37c..000000000 --- a/guidelines/Windows +++ /dev/null @@ -1,83 +0,0 @@ -Creating the Visual Studio Template Project -=========================================== - -1. Create an empty Visual C++ Win32 Console App project - - Microsoft Visual Studio Express 2013 for Windows Desktop - Open New Project Wizard (File -> New Project..) - - Project Name: YosysVS - Solution Name: YosysVS - [X] Create directory for solution - [ ] Add to source control - - [X] Console applications - [X] Empty Project - [ ] SDL checks - -2. Open YosysVS Project Properties - - Select Configuration: All Configurations - - C/C++ -> General -> Additional Include Directories - Add: ..\yosys - - C/C++ -> Preprocessor -> Preprocessor Definitions - Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS - -3. Resulting file system tree: - - YosysVS/ - YosysVS/YosysVS - YosysVS/YosysVS/YosysVS.vcxproj - YosysVS/YosysVS/YosysVS.vcxproj.filters - YosysVS/YosysVS.sdf - YosysVS/YosysVS.sln - YosysVS/YosysVS.v12.suo - -4. Zip YosysVS as YosysVS-Tpl-v1.zip - -Compiling with Visual Studio -============================ - -Visual Studio builds are not directly supported by build scripts, but they are still possible. - -1. Easy way - - - Go to https://github.com/YosysHQ/yosys/actions/workflows/vs.yml?query=branch%3Amain - - Click on the most recent completed run - - In Artifacts region find vcxsrc and click on it to download - - Unpack downloaded ZIP file - - Open YosysVS.sln with Visual Studio - -2. Using WSL or MSYS2 - - - Make sure to have make, python3 and git available - - Git clone yosys repository - - Execute ```make vcxsrc YOSYS_VER=latest``` - - File yosys-win32-vcxsrc-latest.zip will be created - - Transfer that file to location visible by Windows application - - Unpack ZIP - - Open YosysVS.sln with Visual Studio - -Cross-Building for Windows with MXE -=================================== - -Check http://mxe.cc/#requirements and install all missing requirements. - -As root (or other user with write access to /usr/local/src): - - cd /usr/local/src - git clone https://github.com/mxe/mxe.git - cd mxe - - make -j$(nproc) MXE_PLUGIN_DIRS="plugins/tcl.tk" \ - MXE_TARGETS="i686-w64-mingw32.static" \ - gcc tcl readline - -Then as regular user in some directory where you build stuff: - - git clone https://github.com/YosysHQ/yosys.git yosys-win32 - cd yosys-win32 - make config-mxe - make -j$(nproc) mxebin diff --git a/kernel/bitpattern.h b/kernel/bitpattern.h index 7a8eb39f9..821490dca 100644 --- a/kernel/bitpattern.h +++ b/kernel/bitpattern.h @@ -30,7 +30,7 @@ struct BitPatternPool int width; struct bits_t { std::vector bitdata; - mutable unsigned int cached_hash; + mutable Hasher::hash_t cached_hash; bits_t(int width = 0) : bitdata(width), cached_hash(0) { } RTLIL::State &operator[](int index) { return bitdata[index]; @@ -39,14 +39,15 @@ struct BitPatternPool return bitdata[index]; } bool operator==(const bits_t &other) const { - if (hash() != other.hash()) + if (run_hash(*this) != run_hash(other)) return false; return bitdata == other.bitdata; } - unsigned int hash() const { + [[nodiscard]] Hasher hash_into(Hasher h) const { if (!cached_hash) - cached_hash = hash_ops>::hash(bitdata); - return cached_hash; + cached_hash = run_hash(bitdata); + h.eat(cached_hash); + return h; } }; pool database; @@ -80,7 +81,7 @@ struct BitPatternPool bits_t sig2bits(RTLIL::SigSpec sig) { bits_t bits; - bits.bitdata = sig.as_const().bits; + bits.bitdata = sig.as_const().bits(); for (auto &b : bits.bitdata) if (b > RTLIL::State::S1) b = RTLIL::State::Sa; diff --git a/kernel/calc.cc b/kernel/calc.cc index 9b02a6e30..f08c97396 100644 --- a/kernel/calc.cc +++ b/kernel/calc.cc @@ -30,13 +30,13 @@ static void extend_u0(RTLIL::Const &arg, int width, bool is_signed) { RTLIL::State padding = RTLIL::State::S0; - if (arg.bits.size() > 0 && is_signed) - padding = arg.bits.back(); + if (arg.size() > 0 && is_signed) + padding = arg.back(); - while (int(arg.bits.size()) < width) - arg.bits.push_back(padding); + while (GetSize(arg) < width) + arg.bits().push_back(padding); - arg.bits.resize(width); + arg.bits().resize(width); } static BigInteger const2big(const RTLIL::Const &val, bool as_signed, int &undef_bit_pos) @@ -45,17 +45,17 @@ static BigInteger const2big(const RTLIL::Const &val, bool as_signed, int &undef_ BigInteger::Sign sign = BigInteger::positive; State inv_sign_bit = RTLIL::State::S1; - size_t num_bits = val.bits.size(); + auto num_bits = val.size(); - if (as_signed && num_bits && val.bits[num_bits-1] == RTLIL::State::S1) { + if (as_signed && num_bits && val[num_bits-1] == RTLIL::State::S1) { inv_sign_bit = RTLIL::State::S0; sign = BigInteger::negative; num_bits--; } - for (size_t i = 0; i < num_bits; i++) - if (val.bits[i] == RTLIL::State::S0 || val.bits[i] == RTLIL::State::S1) - mag.setBit(i, val.bits[i] == inv_sign_bit); + for (auto i = 0; i < num_bits; i++) + if (val[i] == RTLIL::State::S0 || val[i] == RTLIL::State::S1) + mag.setBit(i, val[i] == inv_sign_bit); else if (undef_bit_pos < 0) undef_bit_pos = i; @@ -78,20 +78,20 @@ static RTLIL::Const big2const(const BigInteger &val, int result_len, int undef_b if (val.getSign() < 0) { mag--; - for (int i = 0; i < result_len; i++) - result.bits[i] = mag.getBit(i) ? RTLIL::State::S0 : RTLIL::State::S1; + for (auto i = 0; i < result_len; i++) + result.bits()[i] = mag.getBit(i) ? RTLIL::State::S0 : RTLIL::State::S1; } else { - for (int i = 0; i < result_len; i++) - result.bits[i] = mag.getBit(i) ? RTLIL::State::S1 : RTLIL::State::S0; + for (auto i = 0; i < result_len; i++) + result.bits()[i] = mag.getBit(i) ? RTLIL::State::S1 : RTLIL::State::S0; } } #if 0 if (undef_bit_pos >= 0) for (int i = undef_bit_pos; i < result_len; i++) - result.bits[i] = RTLIL::State::Sx; + result[i] = RTLIL::State::Sx; #endif return result; @@ -132,19 +132,19 @@ static RTLIL::State logic_xnor(RTLIL::State a, RTLIL::State b) RTLIL::Const RTLIL::const_not(const RTLIL::Const &arg1, const RTLIL::Const&, bool signed1, bool, int result_len) { if (result_len < 0) - result_len = arg1.bits.size(); + result_len = GetSize(arg1); RTLIL::Const arg1_ext = arg1; extend_u0(arg1_ext, result_len, signed1); RTLIL::Const result(RTLIL::State::Sx, result_len); - for (size_t i = 0; i < size_t(result_len); i++) { - if (i >= arg1_ext.bits.size()) - result.bits[i] = RTLIL::State::S0; - else if (arg1_ext.bits[i] == RTLIL::State::S0) - result.bits[i] = RTLIL::State::S1; - else if (arg1_ext.bits[i] == RTLIL::State::S1) - result.bits[i] = RTLIL::State::S0; + for (auto i = 0; i < result_len; i++) { + if (i >= GetSize(arg1_ext)) + result.bits()[i] = RTLIL::State::S0; + else if (arg1_ext.bits()[i] == RTLIL::State::S0) + result.bits()[i] = RTLIL::State::S1; + else if (arg1_ext.bits()[i] == RTLIL::State::S1) + result.bits()[i] = RTLIL::State::S0; } return result; @@ -154,16 +154,16 @@ static RTLIL::Const logic_wrapper(RTLIL::State(*logic_func)(RTLIL::State, RTLIL: RTLIL::Const arg1, RTLIL::Const arg2, bool signed1, bool signed2, int result_len = -1) { if (result_len < 0) - result_len = max(arg1.bits.size(), arg2.bits.size()); + result_len = max(GetSize(arg1), GetSize(arg2)); extend_u0(arg1, result_len, signed1); extend_u0(arg2, result_len, signed2); RTLIL::Const result(RTLIL::State::Sx, result_len); - for (size_t i = 0; i < size_t(result_len); i++) { - RTLIL::State a = i < arg1.bits.size() ? arg1.bits[i] : RTLIL::State::S0; - RTLIL::State b = i < arg2.bits.size() ? arg2.bits[i] : RTLIL::State::S0; - result.bits[i] = logic_func(a, b); + for (auto i = 0; i < result_len; i++) { + RTLIL::State a = i < GetSize(arg1) ? arg1.bits()[i] : RTLIL::State::S0; + RTLIL::State b = i < GetSize(arg2) ? arg2.bits()[i] : RTLIL::State::S0; + result.bits()[i] = logic_func(a, b); } return result; @@ -193,12 +193,12 @@ static RTLIL::Const logic_reduce_wrapper(RTLIL::State initial, RTLIL::State(*log { RTLIL::State temp = initial; - for (size_t i = 0; i < arg1.bits.size(); i++) - temp = logic_func(temp, arg1.bits[i]); + for (auto i = 0; i < arg1.size(); i++) + temp = logic_func(temp, arg1[i]); RTLIL::Const result(temp); - while (int(result.bits.size()) < result_len) - result.bits.push_back(RTLIL::State::S0); + while (GetSize(result) < result_len) + result.bits().push_back(RTLIL::State::S0); return result; } @@ -220,11 +220,11 @@ RTLIL::Const RTLIL::const_reduce_xor(const RTLIL::Const &arg1, const RTLIL::Cons RTLIL::Const RTLIL::const_reduce_xnor(const RTLIL::Const &arg1, const RTLIL::Const&, bool, bool, int result_len) { RTLIL::Const buffer = logic_reduce_wrapper(RTLIL::State::S0, logic_xor, arg1, result_len); - if (!buffer.bits.empty()) { - if (buffer.bits.front() == RTLIL::State::S0) - buffer.bits.front() = RTLIL::State::S1; - else if (buffer.bits.front() == RTLIL::State::S1) - buffer.bits.front() = RTLIL::State::S0; + if (!buffer.empty()) { + if (buffer.front() == RTLIL::State::S0) + buffer.bits().front() = RTLIL::State::S1; + else if (buffer.front() == RTLIL::State::S1) + buffer.bits().front() = RTLIL::State::S0; } return buffer; } @@ -240,8 +240,8 @@ RTLIL::Const RTLIL::const_logic_not(const RTLIL::Const &arg1, const RTLIL::Const BigInteger a = const2big(arg1, signed1, undef_bit_pos_a); RTLIL::Const result(a.isZero() ? undef_bit_pos_a >= 0 ? RTLIL::State::Sx : RTLIL::State::S1 : RTLIL::State::S0); - while (int(result.bits.size()) < result_len) - result.bits.push_back(RTLIL::State::S0); + while (GetSize(result) < result_len) + result.bits().push_back(RTLIL::State::S0); return result; } @@ -255,8 +255,8 @@ RTLIL::Const RTLIL::const_logic_and(const RTLIL::Const &arg1, const RTLIL::Const RTLIL::State bit_b = b.isZero() ? undef_bit_pos_b >= 0 ? RTLIL::State::Sx : RTLIL::State::S0 : RTLIL::State::S1; RTLIL::Const result(logic_and(bit_a, bit_b)); - while (int(result.bits.size()) < result_len) - result.bits.push_back(RTLIL::State::S0); + while (GetSize(result) < result_len) + result.bits().push_back(RTLIL::State::S0); return result; } @@ -270,8 +270,8 @@ RTLIL::Const RTLIL::const_logic_or(const RTLIL::Const &arg1, const RTLIL::Const RTLIL::State bit_b = b.isZero() ? undef_bit_pos_b >= 0 ? RTLIL::State::Sx : RTLIL::State::S0 : RTLIL::State::S1; RTLIL::Const result(logic_or(bit_a, bit_b)); - while (int(result.bits.size()) < result_len) - result.bits.push_back(RTLIL::State::S0); + while (GetSize(result) < result_len) + result.bits().push_back(RTLIL::State::S0); return result; } @@ -286,7 +286,7 @@ static RTLIL::Const const_shift_worker(const RTLIL::Const &arg1, const RTLIL::Co BigInteger offset = const2big(arg2, signed2, undef_bit_pos) * direction; if (result_len < 0) - result_len = arg1.bits.size(); + result_len = GetSize(arg1); RTLIL::Const result(RTLIL::State::Sx, result_len); if (undef_bit_pos >= 0) @@ -295,11 +295,11 @@ static RTLIL::Const const_shift_worker(const RTLIL::Const &arg1, const RTLIL::Co for (int i = 0; i < result_len; i++) { BigInteger pos = BigInteger(i) + offset; if (pos < 0) - result.bits[i] = vacant_bits; - else if (pos >= BigInteger(int(arg1.bits.size()))) - result.bits[i] = sign_ext ? arg1.bits.back() : vacant_bits; + result.bits()[i] = vacant_bits; + else if (pos >= BigInteger(GetSize(arg1))) + result.bits()[i] = sign_ext ? arg1.back() : vacant_bits; else - result.bits[i] = arg1.bits[pos.toInt()]; + result.bits()[i] = arg1[pos.toInt()]; } return result; @@ -347,8 +347,8 @@ RTLIL::Const RTLIL::const_lt(const RTLIL::Const &arg1, const RTLIL::Const &arg2, bool y = const2big(arg1, signed1, undef_bit_pos) < const2big(arg2, signed2, undef_bit_pos); RTLIL::Const result(undef_bit_pos >= 0 ? RTLIL::State::Sx : y ? RTLIL::State::S1 : RTLIL::State::S0); - while (int(result.bits.size()) < result_len) - result.bits.push_back(RTLIL::State::S0); + while (GetSize(result) < result_len) + result.bits().push_back(RTLIL::State::S0); return result; } @@ -358,8 +358,8 @@ RTLIL::Const RTLIL::const_le(const RTLIL::Const &arg1, const RTLIL::Const &arg2, bool y = const2big(arg1, signed1, undef_bit_pos) <= const2big(arg2, signed2, undef_bit_pos); RTLIL::Const result(undef_bit_pos >= 0 ? RTLIL::State::Sx : y ? RTLIL::State::S1 : RTLIL::State::S0); - while (int(result.bits.size()) < result_len) - result.bits.push_back(RTLIL::State::S0); + while (GetSize(result) < result_len) + result.bits().push_back(RTLIL::State::S0); return result; } @@ -369,31 +369,31 @@ RTLIL::Const RTLIL::const_eq(const RTLIL::Const &arg1, const RTLIL::Const &arg2, RTLIL::Const arg2_ext = arg2; RTLIL::Const result(RTLIL::State::S0, result_len); - int width = max(arg1_ext.bits.size(), arg2_ext.bits.size()); + int width = max(GetSize(arg1_ext), GetSize(arg2_ext)); extend_u0(arg1_ext, width, signed1 && signed2); extend_u0(arg2_ext, width, signed1 && signed2); RTLIL::State matched_status = RTLIL::State::S1; - for (size_t i = 0; i < arg1_ext.bits.size(); i++) { - if (arg1_ext.bits.at(i) == RTLIL::State::S0 && arg2_ext.bits.at(i) == RTLIL::State::S1) + for (auto i = 0; i < arg1_ext.size(); i++) { + if (arg1_ext.at(i) == RTLIL::State::S0 && arg2_ext.at(i) == RTLIL::State::S1) return result; - if (arg1_ext.bits.at(i) == RTLIL::State::S1 && arg2_ext.bits.at(i) == RTLIL::State::S0) + if (arg1_ext.at(i) == RTLIL::State::S1 && arg2_ext.at(i) == RTLIL::State::S0) return result; - if (arg1_ext.bits.at(i) > RTLIL::State::S1 || arg2_ext.bits.at(i) > RTLIL::State::S1) + if (arg1_ext.at(i) > RTLIL::State::S1 || arg2_ext.at(i) > RTLIL::State::S1) matched_status = RTLIL::State::Sx; } - result.bits.front() = matched_status; + result.bits().front() = matched_status; return result; } RTLIL::Const RTLIL::const_ne(const RTLIL::Const &arg1, const RTLIL::Const &arg2, bool signed1, bool signed2, int result_len) { RTLIL::Const result = RTLIL::const_eq(arg1, arg2, signed1, signed2, result_len); - if (result.bits.front() == RTLIL::State::S0) - result.bits.front() = RTLIL::State::S1; - else if (result.bits.front() == RTLIL::State::S1) - result.bits.front() = RTLIL::State::S0; + if (result.front() == RTLIL::State::S0) + result.bits().front() = RTLIL::State::S1; + else if (result.front() == RTLIL::State::S1) + result.bits().front() = RTLIL::State::S0; return result; } @@ -403,26 +403,26 @@ RTLIL::Const RTLIL::const_eqx(const RTLIL::Const &arg1, const RTLIL::Const &arg2 RTLIL::Const arg2_ext = arg2; RTLIL::Const result(RTLIL::State::S0, result_len); - int width = max(arg1_ext.bits.size(), arg2_ext.bits.size()); + int width = max(GetSize(arg1_ext), GetSize(arg2_ext)); extend_u0(arg1_ext, width, signed1 && signed2); extend_u0(arg2_ext, width, signed1 && signed2); - for (size_t i = 0; i < arg1_ext.bits.size(); i++) { - if (arg1_ext.bits.at(i) != arg2_ext.bits.at(i)) + for (auto i = 0; i < arg1_ext.size(); i++) { + if (arg1_ext.at(i) != arg2_ext.at(i)) return result; } - result.bits.front() = RTLIL::State::S1; + result.bits().front() = RTLIL::State::S1; return result; } RTLIL::Const RTLIL::const_nex(const RTLIL::Const &arg1, const RTLIL::Const &arg2, bool signed1, bool signed2, int result_len) { RTLIL::Const result = RTLIL::const_eqx(arg1, arg2, signed1, signed2, result_len); - if (result.bits.front() == RTLIL::State::S0) - result.bits.front() = RTLIL::State::S1; - else if (result.bits.front() == RTLIL::State::S1) - result.bits.front() = RTLIL::State::S0; + if (result.front() == RTLIL::State::S0) + result.bits().front() = RTLIL::State::S1; + else if (result.front() == RTLIL::State::S1) + result.bits().front() = RTLIL::State::S0; return result; } @@ -432,8 +432,8 @@ RTLIL::Const RTLIL::const_ge(const RTLIL::Const &arg1, const RTLIL::Const &arg2, bool y = const2big(arg1, signed1, undef_bit_pos) >= const2big(arg2, signed2, undef_bit_pos); RTLIL::Const result(undef_bit_pos >= 0 ? RTLIL::State::Sx : y ? RTLIL::State::S1 : RTLIL::State::S0); - while (int(result.bits.size()) < result_len) - result.bits.push_back(RTLIL::State::S0); + while (GetSize(result) < result_len) + result.bits().push_back(RTLIL::State::S0); return result; } @@ -443,8 +443,8 @@ RTLIL::Const RTLIL::const_gt(const RTLIL::Const &arg1, const RTLIL::Const &arg2, bool y = const2big(arg1, signed1, undef_bit_pos) > const2big(arg2, signed2, undef_bit_pos); RTLIL::Const result(undef_bit_pos >= 0 ? RTLIL::State::Sx : y ? RTLIL::State::S1 : RTLIL::State::S0); - while (int(result.bits.size()) < result_len) - result.bits.push_back(RTLIL::State::S0); + while (GetSize(result) < result_len) + result.bits().push_back(RTLIL::State::S0); return result; } @@ -452,21 +452,21 @@ RTLIL::Const RTLIL::const_add(const RTLIL::Const &arg1, const RTLIL::Const &arg2 { int undef_bit_pos = -1; BigInteger y = const2big(arg1, signed1, undef_bit_pos) + const2big(arg2, signed2, undef_bit_pos); - return big2const(y, result_len >= 0 ? result_len : max(arg1.bits.size(), arg2.bits.size()), undef_bit_pos); + return big2const(y, result_len >= 0 ? result_len : max(GetSize(arg1), GetSize(arg2)), undef_bit_pos); } RTLIL::Const RTLIL::const_sub(const RTLIL::Const &arg1, const RTLIL::Const &arg2, bool signed1, bool signed2, int result_len) { int undef_bit_pos = -1; BigInteger y = const2big(arg1, signed1, undef_bit_pos) - const2big(arg2, signed2, undef_bit_pos); - return big2const(y, result_len >= 0 ? result_len : max(arg1.bits.size(), arg2.bits.size()), undef_bit_pos); + return big2const(y, result_len >= 0 ? result_len : max(GetSize(arg1), GetSize(arg2)), undef_bit_pos); } RTLIL::Const RTLIL::const_mul(const RTLIL::Const &arg1, const RTLIL::Const &arg2, bool signed1, bool signed2, int result_len) { int undef_bit_pos = -1; BigInteger y = const2big(arg1, signed1, undef_bit_pos) * const2big(arg2, signed2, undef_bit_pos); - return big2const(y, result_len >= 0 ? result_len : max(arg1.bits.size(), arg2.bits.size()), min(undef_bit_pos, 0)); + return big2const(y, result_len >= 0 ? result_len : max(GetSize(arg1), GetSize(arg2)), min(undef_bit_pos, 0)); } // truncating division @@ -480,7 +480,7 @@ RTLIL::Const RTLIL::const_div(const RTLIL::Const &arg1, const RTLIL::Const &arg2 bool result_neg = (a.getSign() == BigInteger::negative) != (b.getSign() == BigInteger::negative); a = a.getSign() == BigInteger::negative ? -a : a; b = b.getSign() == BigInteger::negative ? -b : b; - return big2const(result_neg ? -(a / b) : (a / b), result_len >= 0 ? result_len : max(arg1.bits.size(), arg2.bits.size()), min(undef_bit_pos, 0)); + return big2const(result_neg ? -(a / b) : (a / b), result_len >= 0 ? result_len : max(GetSize(arg1), GetSize(arg2)), min(undef_bit_pos, 0)); } // truncating modulo @@ -494,7 +494,7 @@ RTLIL::Const RTLIL::const_mod(const RTLIL::Const &arg1, const RTLIL::Const &arg2 bool result_neg = a.getSign() == BigInteger::negative; a = a.getSign() == BigInteger::negative ? -a : a; b = b.getSign() == BigInteger::negative ? -b : b; - return big2const(result_neg ? -(a % b) : (a % b), result_len >= 0 ? result_len : max(arg1.bits.size(), arg2.bits.size()), min(undef_bit_pos, 0)); + return big2const(result_neg ? -(a % b) : (a % b), result_len >= 0 ? result_len : max(GetSize(arg1), GetSize(arg2)), min(undef_bit_pos, 0)); } RTLIL::Const RTLIL::const_divfloor(const RTLIL::Const &arg1, const RTLIL::Const &arg2, bool signed1, bool signed2, int result_len) @@ -516,7 +516,7 @@ RTLIL::Const RTLIL::const_divfloor(const RTLIL::Const &arg1, const RTLIL::Const // bigint division with negative numbers is wonky, make sure we only negate at the very end result = -((a + b - 1) / b); } - return big2const(result, result_len >= 0 ? result_len : max(arg1.bits.size(), arg2.bits.size()), min(undef_bit_pos, 0)); + return big2const(result, result_len >= 0 ? result_len : max(GetSize(arg1), GetSize(arg2)), min(undef_bit_pos, 0)); } RTLIL::Const RTLIL::const_modfloor(const RTLIL::Const &arg1, const RTLIL::Const &arg2, bool signed1, bool signed2, int result_len) @@ -539,7 +539,7 @@ RTLIL::Const RTLIL::const_modfloor(const RTLIL::Const &arg1, const RTLIL::Const } else { modulo = b_sign == BigInteger::negative ? truncated - b : truncated + b; } - return big2const(modulo, result_len >= 0 ? result_len : max(arg1.bits.size(), arg2.bits.size()), min(undef_bit_pos, 0)); + return big2const(modulo, result_len >= 0 ? result_len : max(GetSize(arg1), GetSize(arg2)), min(undef_bit_pos, 0)); } RTLIL::Const RTLIL::const_pow(const RTLIL::Const &arg1, const RTLIL::Const &arg2, bool signed1, bool signed2, int result_len) @@ -590,7 +590,7 @@ RTLIL::Const RTLIL::const_pow(const RTLIL::Const &arg1, const RTLIL::Const &arg2 y *= -1; } - return big2const(y, result_len >= 0 ? result_len : max(arg1.bits.size(), arg2.bits.size()), min(undef_bit_pos, 0)); + return big2const(y, result_len >= 0 ? result_len : max(GetSize(arg1), GetSize(arg2)), min(undef_bit_pos, 0)); } RTLIL::Const RTLIL::const_pos(const RTLIL::Const &arg1, const RTLIL::Const&, bool signed1, bool, int result_len) @@ -601,6 +601,14 @@ RTLIL::Const RTLIL::const_pos(const RTLIL::Const &arg1, const RTLIL::Const&, boo return arg1_ext; } +RTLIL::Const RTLIL::const_buf(const RTLIL::Const &arg1, const RTLIL::Const&, bool signed1, bool, int result_len) +{ + RTLIL::Const arg1_ext = arg1; + extend_u0(arg1_ext, result_len, signed1); + + return arg1_ext; +} + RTLIL::Const RTLIL::const_neg(const RTLIL::Const &arg1, const RTLIL::Const&, bool signed1, bool, int result_len) { RTLIL::Const arg1_ext = arg1; @@ -618,9 +626,9 @@ RTLIL::Const RTLIL::const_mux(const RTLIL::Const &arg1, const RTLIL::Const &arg2 return arg2; RTLIL::Const ret = arg1; - for (int i = 0; i < ret.size(); i++) + for (auto i = 0; i < ret.size(); i++) if (ret[i] != arg2[i]) - ret[i] = State::Sx; + ret.bits()[i] = State::Sx; return ret; } @@ -632,20 +640,20 @@ RTLIL::Const RTLIL::const_pmux(const RTLIL::Const &arg1, const RTLIL::Const &arg if (!arg3.is_onehot()) return RTLIL::Const(State::Sx, arg1.size()); - for (int i = 0; i < arg3.size(); i++) + for (auto i = 0; i < arg3.size(); i++) if (arg3[i] == State::S1) - return RTLIL::Const(std::vector(arg2.bits.begin() + i*arg1.bits.size(), arg2.bits.begin() + (i+1)*arg1.bits.size())); + return RTLIL::Const(std::vector(arg2.begin() + i*arg1.size(), arg2.begin() + (i+1)*arg1.size())); log_abort(); // unreachable } RTLIL::Const RTLIL::const_bmux(const RTLIL::Const &arg1, const RTLIL::Const &arg2) { - std::vector t = arg1.bits; + std::vector t = arg1.to_bits(); for (int i = GetSize(arg2)-1; i >= 0; i--) { - RTLIL::State sel = arg2.bits.at(i); + RTLIL::State sel = arg2.at(i); std::vector new_t; if (sel == State::S0) new_t = std::vector(t.begin(), t.begin() + GetSize(t)/2); @@ -681,10 +689,10 @@ RTLIL::Const RTLIL::const_demux(const RTLIL::Const &arg1, const RTLIL::Const &ar res.push_back(State::S0); } else if (x) { for (int j = 0; j < width; j++) - res.push_back(arg1.bits[j] == State::S0 ? State::S0 : State::Sx); + res.push_back(arg1[j] == State::S0 ? State::S0 : State::Sx); } else { for (int j = 0; j < width; j++) - res.push_back(arg1.bits[j]); + res.push_back(arg1[j]); } } return res; @@ -694,8 +702,8 @@ RTLIL::Const RTLIL::const_bweqx(const RTLIL::Const &arg1, const RTLIL::Const &ar { log_assert(arg2.size() == arg1.size()); RTLIL::Const result(RTLIL::State::S0, arg1.size()); - for (int i = 0; i < arg1.size(); i++) - result[i] = arg1[i] == arg2[i] ? State::S1 : State::S0; + for (auto i = 0; i < arg1.size(); i++) + result.bits()[i] = arg1[i] == arg2[i] ? State::S1 : State::S0; return result; } @@ -705,9 +713,9 @@ RTLIL::Const RTLIL::const_bwmux(const RTLIL::Const &arg1, const RTLIL::Const &ar log_assert(arg2.size() == arg1.size()); log_assert(arg3.size() == arg1.size()); RTLIL::Const result(RTLIL::State::Sx, arg1.size()); - for (int i = 0; i < arg1.size(); i++) { + for (auto i = 0; i < arg1.size(); i++) { if (arg3[i] != State::Sx || arg1[i] == arg2[i]) - result[i] = arg3[i] == State::S1 ? arg2[i] : arg1[i]; + result.bits()[i] = arg3[i] == State::S1 ? arg2[i] : arg1[i]; } return result; diff --git a/kernel/cellaigs.cc b/kernel/cellaigs.cc index 5dda4503f..fd3c7bb67 100644 --- a/kernel/cellaigs.cc +++ b/kernel/cellaigs.cc @@ -39,13 +39,13 @@ bool AigNode::operator==(const AigNode &other) const return true; } -unsigned int AigNode::hash() const +Hasher AigNode::hash_into(Hasher h) const { - unsigned int h = mkhash_init; - h = mkhash(portname.hash(), portbit); - h = mkhash(h, inverter); - h = mkhash(h, left_parent); - h = mkhash(h, right_parent); + h.eat(portname); + h.eat(portbit); + h.eat(inverter); + h.eat(left_parent); + h.eat(right_parent); return h; } @@ -54,9 +54,10 @@ bool Aig::operator==(const Aig &other) const return name == other.name; } -unsigned int Aig::hash() const +Hasher Aig::hash_into(Hasher h) const { - return hash_ops::hash(name); + h.eat(name); + return h; } struct AigMaker @@ -290,7 +291,7 @@ Aig::Aig(Cell *cell) } } - if (cell->type.in(ID($not), ID($_NOT_), ID($pos), ID($_BUF_))) + if (cell->type.in(ID($not), ID($_NOT_), ID($pos), ID($buf), ID($_BUF_))) { for (int i = 0; i < GetSize(cell->getPort(ID::Y)); i++) { int A = mk.inport(ID::A, i); diff --git a/kernel/cellaigs.h b/kernel/cellaigs.h index 8f6d69ba6..f6afcde5e 100644 --- a/kernel/cellaigs.h +++ b/kernel/cellaigs.h @@ -34,7 +34,7 @@ struct AigNode AigNode(); bool operator==(const AigNode &other) const; - unsigned int hash() const; + [[nodiscard]] Hasher hash_into(Hasher h) const; }; struct Aig @@ -44,7 +44,7 @@ struct Aig Aig(Cell *cell); bool operator==(const Aig &other) const; - unsigned int hash() const; + [[nodiscard]] Hasher hash_into(Hasher h) const; }; YOSYS_NAMESPACE_END diff --git a/kernel/celledges.cc b/kernel/celledges.cc index 09cdfd55b..8e52d0380 100644 --- a/kernel/celledges.cc +++ b/kernel/celledges.cc @@ -24,7 +24,7 @@ PRIVATE_NAMESPACE_BEGIN void bitwise_unary_op(AbstractCellEdgesDatabase *db, RTLIL::Cell *cell) { - bool is_signed = cell->getParam(ID::A_SIGNED).as_bool(); + bool is_signed = (cell->type != ID($buf)) && cell->getParam(ID::A_SIGNED).as_bool(); int a_width = GetSize(cell->getPort(ID::A)); int y_width = GetSize(cell->getPort(ID::Y)); @@ -247,19 +247,19 @@ void shift_op(AbstractCellEdgesDatabase *db, RTLIL::Cell *cell) db->add_edge(cell, ID::A, a_width - 1, ID::Y, i, -1); } - for (int k = 0; k < b_width; k++) { + for (int k = 0; k < b_width_capped; k++) { // left shifts if (cell->type.in(ID($shl), ID($sshl))) { if (a_width == 1 && is_signed) { int skip = 1 << (k + 1); int base = skip -1; - if (i % skip != base && i - a_width + 2 < 1 << b_width) + if (i % skip != base && i - a_width + 2 < 1 << b_width_capped) db->add_edge(cell, ID::B, k, ID::Y, i, -1); } else if (is_signed) { - if (i - a_width + 2 < 1 << b_width) + if (i - a_width + 2 < 1 << b_width_capped) db->add_edge(cell, ID::B, k, ID::Y, i, -1); } else { - if (i - a_width + 1 < 1 << b_width) + if (i - a_width + 1 < 1 << b_width_capped) db->add_edge(cell, ID::B, k, ID::Y, i, -1); } // right shifts @@ -268,7 +268,7 @@ void shift_op(AbstractCellEdgesDatabase *db, RTLIL::Cell *cell) bool shift_in_bulk = i < a_width - 1; // can we jump into the zero-padding by toggling B[k]? bool zpad_jump = (((y_width - i) & ((1 << (k + 1)) - 1)) != 0 \ - && (((y_width - i) & ~(1 << k)) < (1 << b_width))); + && (((y_width - i) & ~(1 << k)) < (1 << b_width_capped))); if (shift_in_bulk || (cell->type.in(ID($shr), ID($shift), ID($shiftx)) && zpad_jump)) db->add_edge(cell, ID::B, k, ID::Y, i, -1); @@ -279,7 +279,7 @@ void shift_op(AbstractCellEdgesDatabase *db, RTLIL::Cell *cell) // bidirectional shifts (positive B shifts right, negative left) } else if (cell->type.in(ID($shift), ID($shiftx)) && is_b_signed) { if (is_signed) { - if (k != b_width - 1) { + if (k != b_width_capped - 1) { bool r_shift_in_bulk = i < a_width - 1; // assuming B is positive, can we jump into the upper zero-padding by toggling B[k]? bool r_zpad_jump = (((y_width - i) & ((1 << (k + 1)) - 1)) != 0 \ @@ -392,7 +392,7 @@ PRIVATE_NAMESPACE_END bool YOSYS_NAMESPACE_PREFIX AbstractCellEdgesDatabase::add_edges_from_cell(RTLIL::Cell *cell) { - if (cell->type.in(ID($not), ID($pos))) { + if (cell->type.in(ID($not), ID($pos), ID($buf))) { bitwise_unary_op(this, cell); return true; } @@ -453,7 +453,7 @@ bool YOSYS_NAMESPACE_PREFIX AbstractCellEdgesDatabase::add_edges_from_cell(RTLIL } // FIXME: $mul $div $mod $divfloor $modfloor $slice $concat - // FIXME: $lut $sop $alu $lcu $macc $fa + // FIXME: $lut $sop $alu $lcu $macc $macc_v2 $fa // FIXME: $mul $div $mod $divfloor $modfloor $pow $slice $concat $bweqx // FIXME: $lut $sop $alu $lcu $macc $fa $logic_and $logic_or $bwmux diff --git a/kernel/celltypes.h b/kernel/celltypes.h index fde6624e1..0ce5db54d 100644 --- a/kernel/celltypes.h +++ b/kernel/celltypes.h @@ -29,6 +29,8 @@ struct CellType RTLIL::IdString type; pool inputs, outputs; bool is_evaluable; + bool is_combinatorial; + bool is_synthesizable; }; struct CellTypes @@ -56,9 +58,9 @@ struct CellTypes setup_stdcells_mem(); } - void setup_type(RTLIL::IdString type, const pool &inputs, const pool &outputs, bool is_evaluable = false) + void setup_type(RTLIL::IdString type, const pool &inputs, const pool &outputs, bool is_evaluable = false, bool is_combinatorial = false, bool is_synthesizable = false) { - CellType ct = {type, inputs, outputs, is_evaluable}; + CellType ct = {type, inputs, outputs, is_evaluable, is_combinatorial, is_synthesizable}; cell_types[ct.type] = ct; } @@ -114,7 +116,7 @@ struct CellTypes void setup_internals_eval() { std::vector unary_ops = { - ID($not), ID($pos), ID($neg), + ID($not), ID($pos), ID($buf), ID($neg), ID($reduce_and), ID($reduce_or), ID($reduce_xor), ID($reduce_xnor), ID($reduce_bool), ID($logic_not), ID($slice), ID($lut), ID($sop) }; @@ -142,6 +144,7 @@ struct CellTypes setup_type(ID($lcu), {ID::P, ID::G, ID::CI}, {ID::CO}, true); setup_type(ID($alu), {ID::A, ID::B, ID::CI, ID::BI}, {ID::X, ID::Y, ID::CO}, true); + setup_type(ID($macc_v2), {ID::A, ID::B, ID::C}, {ID::Y}, true); setup_type(ID($fa), {ID::A, ID::B, ID::C}, {ID::X, ID::Y}, true); } @@ -325,7 +328,7 @@ struct CellTypes static RTLIL::Const eval_not(RTLIL::Const v) { - for (auto &bit : v.bits) + for (auto &bit : v.bits()) if (bit == State::S0) bit = State::S1; else if (bit == State::S1) bit = State::S0; return v; @@ -339,7 +342,7 @@ struct CellTypes type = ID($shl); if (type != ID($sshr) && type != ID($sshl) && type != ID($shr) && type != ID($shl) && type != ID($shift) && type != ID($shiftx) && - type != ID($pos) && type != ID($neg) && type != ID($not)) { + type != ID($pos) && type != ID($buf) && type != ID($neg) && type != ID($not)) { if (!signed1 || !signed2) signed1 = false, signed2 = false; } @@ -384,7 +387,7 @@ struct CellTypes HANDLE_CELL_TYPE(neg) #undef HANDLE_CELL_TYPE - if (type == ID($_BUF_)) + if (type.in(ID($_BUF_), ID($buf))) return arg1; if (type == ID($_NOT_)) return eval_not(arg1); @@ -419,13 +422,13 @@ struct CellTypes RTLIL::Const ret; int width = cell->parameters.at(ID::Y_WIDTH).as_int(); int offset = cell->parameters.at(ID::OFFSET).as_int(); - ret.bits.insert(ret.bits.end(), arg1.bits.begin()+offset, arg1.bits.begin()+offset+width); + ret.bits().insert(ret.bits().end(), arg1.begin()+offset, arg1.begin()+offset+width); return ret; } if (cell->type == ID($concat)) { RTLIL::Const ret = arg1; - ret.bits.insert(ret.bits.end(), arg2.bits.begin(), arg2.bits.end()); + ret.bits().insert(ret.bits().end(), arg2.begin(), arg2.end()); return ret; } @@ -448,7 +451,7 @@ struct CellTypes { int width = cell->parameters.at(ID::WIDTH).as_int(); - std::vector t = cell->parameters.at(ID::LUT).bits; + std::vector t = cell->parameters.at(ID::LUT).to_bits(); while (GetSize(t) < (1 << width)) t.push_back(State::S0); t.resize(1 << width); @@ -460,7 +463,7 @@ struct CellTypes { int width = cell->parameters.at(ID::WIDTH).as_int(); int depth = cell->parameters.at(ID::DEPTH).as_int(); - std::vector t = cell->parameters.at(ID::TABLE).bits; + std::vector t = cell->parameters.at(ID::TABLE).to_bits(); while (GetSize(t) < width*depth*2) t.push_back(State::S0); @@ -473,7 +476,7 @@ struct CellTypes bool match_x = true; for (int j = 0; j < width; j++) { - RTLIL::State a = arg1.bits.at(j); + RTLIL::State a = arg1.at(j); if (t.at(2*width*i + 2*j + 0) == State::S1) { if (a == State::S1) match_x = false; if (a != State::S0) match = false; @@ -513,7 +516,7 @@ struct CellTypes if (cell->type == ID($_OAI3_)) return eval_not(const_and(const_or(arg1, arg2, false, false, 1), arg3, false, false, 1)); - log_assert(arg3.bits.size() == 0); + log_assert(arg3.size() == 0); return eval(cell, arg1, arg2, errp); } @@ -524,7 +527,7 @@ struct CellTypes if (cell->type == ID($_OAI4_)) return eval_not(const_and(const_or(arg1, arg2, false, false, 1), const_or(arg3, arg4, false, false, 1), false, false, 1)); - log_assert(arg4.bits.size() == 0); + log_assert(arg4.size() == 0); return eval(cell, arg1, arg2, arg3, errp); } }; diff --git a/kernel/consteval.h b/kernel/consteval.h index 4c0c26049..844120ef0 100644 --- a/kernel/consteval.h +++ b/kernel/consteval.h @@ -76,7 +76,7 @@ struct ConstEval #ifndef NDEBUG RTLIL::SigSpec current_val = values_map(sig); for (int i = 0; i < GetSize(current_val); i++) - log_assert(current_val[i].wire != NULL || current_val[i] == value.bits[i]); + log_assert(current_val[i].wire != NULL || current_val[i] == value[i]); #endif values_map.add(sig, RTLIL::SigSpec(value)); } @@ -115,7 +115,7 @@ struct ConstEval for (int i = 0; i < GetSize(coval); i++) { carry = (sig_g[i] == State::S1) || (sig_p[i] == RTLIL::S1 && carry); - coval.bits[i] = carry ? State::S1 : State::S0; + coval.bits()[i] = carry ? State::S1 : State::S0; } set(sig_co, coval); @@ -153,7 +153,7 @@ struct ConstEval for (int i = 0; i < sig_s.size(); i++) { - RTLIL::State s_bit = sig_s.extract(i, 1).as_const().bits.at(0); + RTLIL::State s_bit = sig_s.extract(i, 1).as_const().at(0); RTLIL::SigSpec b_slice = sig_b.extract(sig_y.size()*i, sig_y.size()); if (s_bit == RTLIL::State::Sx || s_bit == RTLIL::State::S1) @@ -180,10 +180,10 @@ struct ConstEval if (y_values.size() > 1) { - std::vector master_bits = y_values.at(0).bits; + std::vector master_bits = y_values.at(0).to_bits(); for (size_t i = 1; i < y_values.size(); i++) { - std::vector &slave_bits = y_values.at(i).bits; + std::vector slave_bits = y_values.at(i).to_bits(); log_assert(master_bits.size() == slave_bits.size()); for (size_t j = 0; j < master_bits.size(); j++) if (master_bits[j] != slave_bits[j]) @@ -248,8 +248,8 @@ struct ConstEval RTLIL::Const val_x = const_or(t2, t3, false, false, width); for (int i = 0; i < GetSize(val_y); i++) - if (val_y.bits[i] == RTLIL::Sx) - val_x.bits[i] = RTLIL::Sx; + if (val_y[i] == RTLIL::Sx) + val_x.bits()[i] = RTLIL::Sx; set(sig_y, val_y); set(sig_x, val_x); @@ -310,15 +310,12 @@ struct ConstEval } } } - else if (cell->type == ID($macc)) + else if (cell->type.in(ID($macc), ID($macc_v2))) { Macc macc; macc.from_cell(cell); - if (!eval(macc.bit_ports, undef, cell)) - return false; - - for (auto &port : macc.ports) { + for (auto &port : macc.terms) { if (!eval(port.in_a, undef, cell)) return false; if (!eval(port.in_b, undef, cell)) diff --git a/kernel/constids.inc b/kernel/constids.inc index 00db94af4..29872d45e 100644 --- a/kernel/constids.inc +++ b/kernel/constids.inc @@ -43,6 +43,7 @@ X(CE_OVER_SRST) X(CFG_ABITS) X(CFG_DBITS) X(CFG_INIT) +X(chain) X(CI) X(CLK) X(clkbuf_driver) @@ -152,8 +153,8 @@ X(parameter) X(PORTID) X(PRIORITY) X(PRIORITY_MASK) +X(promoted_if) X(Q) -X(qwp_position) X(R) X(ram_block) X(ram_style) @@ -184,6 +185,7 @@ X(romstyle) X(S) X(SET) X(SET_POLARITY) +X(single_bit_vector) X(SIZE) X(SRC) X(src) @@ -274,3 +276,14 @@ X(X) X(xprop_decoder) X(Y) X(Y_WIDTH) +X(area) +X(capacitance) +X(NPRODUCTS) +X(NADDENDS) +X(PRODUCT_NEGATED) +X(ADDEND_NEGATED) +X(A_WIDTHS) +X(B_WIDTHS) +X(C_WIDTHS) +X(C_SIGNED) +X(raise_error) diff --git a/kernel/cost.cc b/kernel/cost.cc index 5d897ab7a..985220f14 100644 --- a/kernel/cost.cc +++ b/kernel/cost.cc @@ -1,4 +1,5 @@ #include "kernel/cost.h" +#include "kernel/macc.h" USING_YOSYS_NAMESPACE @@ -148,6 +149,9 @@ unsigned int CellCosts::get(RTLIL::Cell *cell) log_assert(cell->hasPort(ID::Q) && "Weird flip flop"); log_debug("%s is ff\n", cell->name.c_str()); return cell->getParam(ID::WIDTH).as_int(); + } else if (cell->type.in(ID($mem), ID($mem_v2))) { + log_debug("%s is mem\n", cell->name.c_str()); + return cell->getParam(ID::WIDTH).as_int() * cell->getParam(ID::SIZE).as_int(); } else if (y_coef(cell->type)) { // linear with Y_WIDTH or WIDTH log_assert((cell->hasParam(ID::Y_WIDTH) || cell->hasParam(ID::WIDTH)) && "Unknown width"); @@ -173,6 +177,22 @@ unsigned int CellCosts::get(RTLIL::Cell *cell) unsigned int coef = cell->type == ID($mul) ? 3 : 5; log_debug("%s coef*(sum**2) %d * %d\n", cell->name.c_str(), coef, sum * sum); return coef * sum * sum; + } else if (cell->type.in(ID($macc), ID($macc_v2))) { + // quadratic per term + unsigned int cost_sum = 0; + Macc macc; + macc.from_cell(cell); + unsigned int y_width = cell->getParam(ID::Y_WIDTH).as_int(); + for (auto &term: macc.terms) { + if (term.in_b.empty()) { + // neglect addends + continue; + } + unsigned a_width = term.in_a.size(), b_width = term.in_b.size(); + unsigned int sum = a_width + b_width + std::min(y_width, a_width + b_width); + cost_sum += 3 * sum * sum; + } + return cost_sum; } else if (cell->type == ID($lut)) { int width = cell->getParam(ID::WIDTH).as_int(); unsigned int cost = 1U << (unsigned int)width; @@ -187,8 +207,8 @@ unsigned int CellCosts::get(RTLIL::Cell *cell) log_debug("%s is free\n", cell->name.c_str()); return 0; } - // TODO: $fsm $mem.* $macc - // ignored: $pow + // TODO: $fsm + // ignored: $pow $memrd $memwr $meminit (and v2 counterparts) log_warning("Can't determine cost of %s cell (%d parameters).\n", log_id(cell->type), GetSize(cell->parameters)); return 1; diff --git a/kernel/driver.cc b/kernel/driver.cc index 1e4cd0052..76c11853e 100644 --- a/kernel/driver.cc +++ b/kernel/driver.cc @@ -18,7 +18,11 @@ */ #include "kernel/yosys.h" +#include "kernel/hashlib.h" #include "libs/sha1/sha1.h" +#define CXXOPTS_VECTOR_DELIMITER '\0' +#include "libs/cxxopts/include/cxxopts.hpp" +#include #ifdef YOSYS_ENABLE_READLINE # include @@ -29,6 +33,10 @@ # include #endif +#ifdef YOSYS_ENABLE_TCL +# include +#endif + #include #include #include @@ -55,55 +63,6 @@ USING_YOSYS_NAMESPACE -char *optarg; -int optind = 1, optcur = 1, optopt = 0; -int getopt(int argc, char **argv, const char *optstring) -{ - if (optind >= argc) - return -1; - - if (argv[optind][0] != '-' || argv[optind][1] == 0) { - optopt = 1; - optarg = argv[optind++]; - return optopt; - } - - bool takes_arg = false; - optopt = argv[optind][optcur]; - - if (optopt == '-') { - ++optind; - return -1; - } - - for (int i = 0; optstring[i]; i++) - if (optopt == optstring[i] && optstring[i + 1] == ':') - takes_arg = true; - - if (!takes_arg) { - if (argv[optind][++optcur] == 0) - optind++, optcur = 1; - return optopt; - } - - if (argv[optind][++optcur]) { - optarg = argv[optind++] + optcur; - optcur = 1; - return optopt; - } - - if (++optind >= argc) { - fprintf(stderr, "%s: option '-%c' expects an argument\n", argv[0], optopt); - optopt = '?'; - return optopt; - } - - optarg = argv[optind]; - optind++, optcur = 1; - - return optopt; -} - #ifdef EMSCRIPTEN # include # include @@ -153,7 +112,7 @@ void run(const char *command) log_last_error = ""; } catch (...) { while (GetSize(yosys_get_design()->selection_stack) > selSize) - yosys_get_design()->selection_stack.pop_back(); + yosys_get_design()->pop_selection(); throw; } } @@ -235,12 +194,14 @@ int main(int argc, char **argv) std::vector passes_commands; std::vector frontend_files; std::vector plugin_filenames; + std::vector special_args; std::string output_filename = ""; std::string scriptfile = ""; std::string depsfile = ""; std::string topmodule = ""; std::string perffile = ""; bool scriptfile_tcl = false; + bool scriptfile_python = false; bool print_banner = true; bool print_stats = true; bool call_abort = false; @@ -250,292 +211,257 @@ int main(int argc, char **argv) bool mode_v = false; bool mode_q = false; - if (argc == 2 && (!strcmp(argv[1], "-h") || !strcmp(argv[1], "-help") || !strcmp(argv[1], "--help"))) - { - printf("\n"); - printf("Usage: %s [options] [ [..]]\n", argv[0]); - printf("\n"); - printf(" -Q\n"); - printf(" suppress printing of banner (copyright, disclaimer, version)\n"); - printf("\n"); - printf(" -T\n"); - printf(" suppress printing of footer (log hash, version, timing statistics)\n"); - printf("\n"); - printf(" -q\n"); - printf(" quiet operation. only write warnings and error messages to console\n"); - printf(" use this option twice to also quiet warning messages\n"); - printf("\n"); - printf(" -v \n"); - printf(" print log headers up to level to the console. (this\n"); - printf(" implies -q for everything except the 'End of script.' message.)\n"); - printf("\n"); - printf(" -t\n"); - printf(" annotate all log messages with a time stamp\n"); - printf("\n"); - printf(" -d\n"); - printf(" print more detailed timing stats at exit\n"); - printf("\n"); - printf(" -l logfile\n"); - printf(" write log messages to the specified file\n"); - printf("\n"); - printf(" -L logfile\n"); - printf(" like -l but open log file in line buffered mode\n"); - printf("\n"); - printf(" -o outfile\n"); - printf(" write the design to the specified file on exit\n"); - printf("\n"); - printf(" -b backend\n"); - printf(" use this backend for the output file specified on the command line\n"); - printf("\n"); - printf(" -f frontend\n"); - printf(" use the specified frontend for the input files on the command line\n"); - printf("\n"); - printf(" -H\n"); - printf(" print the command list\n"); - printf("\n"); - printf(" -h command\n"); - printf(" print the help message for the specified command\n"); - printf("\n"); - printf(" -s scriptfile\n"); - printf(" execute the commands in the script file\n"); + cxxopts::Options options(argv[0], "Yosys Open SYnthesis Suite"); + options.set_width(SIZE_MAX); + + options.add_options("operation") + ("b,backend", "use for the output file specified on the command line", + cxxopts::value(), "") + ("f,frontend", "use for the input files on the command line", + cxxopts::value(), "") + ("s,scriptfile", "execute the commands in ", + cxxopts::value(), "") #ifdef YOSYS_ENABLE_TCL - printf("\n"); - printf(" -c tcl_scriptfile\n"); - printf(" execute the commands in the tcl script file (see 'help tcl' for details)\n"); - printf("\n"); - printf(" -C\n"); - printf(" enters TCL interatcive shell mode\n"); -#endif - printf("\n"); - printf(" -p command\n"); - printf(" execute the commands (to chain commands, separate them with semicolon + whitespace: 'cmd1; cmd2')\n"); - printf("\n"); - printf(" -m module_file\n"); - printf(" load the specified module (aka plugin)\n"); - printf("\n"); - printf(" -X\n"); - printf(" enable tracing of core data structure changes. for debugging\n"); - printf("\n"); - printf(" -M\n"); - printf(" will slightly randomize allocated pointer addresses. for debugging\n"); - printf("\n"); - printf(" -A\n"); - printf(" will call abort() at the end of the script. for debugging\n"); - printf("\n"); - printf(" -r \n"); - printf(" elaborate command line arguments using the specified top module\n"); - printf("\n"); - printf(" -D [=]\n"); - printf(" set the specified Verilog define (via \"read -define\")\n"); - printf("\n"); - printf(" -P [:]\n"); - printf(" dump the design when printing the specified log header to a file.\n"); - printf(" yosys_dump_.il is used as filename if none is specified.\n"); - printf(" Use 'ALL' as to dump at every header.\n"); - printf("\n"); - printf(" -W regex\n"); - printf(" print a warning for all log messages matching the regex.\n"); - printf("\n"); - printf(" -w regex\n"); - printf(" if a warning message matches the regex, it is printed as regular\n"); - printf(" message instead.\n"); - printf("\n"); - printf(" -e regex\n"); - printf(" if a warning message matches the regex, it is printed as error\n"); - printf(" message instead and the tool terminates with a nonzero return code.\n"); - printf("\n"); - printf(" -E \n"); - printf(" write a Makefile dependencies file with in- and output file names\n"); - printf("\n"); - printf(" -x \n"); - printf(" do not print warnings for the specified experimental feature\n"); - printf("\n"); - printf(" -g\n"); - printf(" globally enable debug log messages\n"); - printf("\n"); - printf(" -V\n"); - printf(" print version information and exit\n"); - printf("\n"); - printf("The option -S is a shortcut for calling the \"synth\" command, a default\n"); - printf("script for transforming the Verilog input to a gate-level netlist. For example:\n"); - printf("\n"); - printf(" yosys -o output.blif -S input.v\n"); - printf("\n"); - printf("For more complex synthesis jobs it is recommended to use the read_* and write_*\n"); - printf("commands in a script file instead of specifying input and output files on the\n"); - printf("command line.\n"); - printf("\n"); - printf("When no commands, script files or input files are specified on the command\n"); - printf("line, yosys automatically enters the interactive command mode. Use the 'help'\n"); - printf("command to get information on the individual commands.\n"); - printf("\n"); + ("c,tcl-scriptfile", "execute the commands in the TCL (see 'help tcl' for details)", + cxxopts::value(),"") + ("C,tcl-interactive", "enters TCL interactive shell mode") +#endif // YOSYS_ENABLE_TCL +#ifdef WITH_PYTHON + ("y,py-scriptfile", "execute the Python