Initial commit

.ci/build_docs.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+set -xeou pipefail
+
+cabal haddock --enable-documentation clash-protocols |& tee haddock_log
+
+set +e
+if grep -q "Missing documentation" haddock_log; then
+  echo -e "\e[1m\e[31mMissing documentation! Scroll up for full log.\e[0m"
+  grep --color=always -n -C 5 "Missing documentation" haddock_log
+  exit 1
+fi
+
+if grep -q "If you qualify the identifier, haddock can try to link it anyway" haddock_log; then
+  echo -e "\e[1m\e[31mIdentifier out of scope! Scroll up for full log.\e[0m"
+  grep --color=always -n -C 5 "If you qualify the identifier, haddock can try to link it anyway" haddock_log
+  exit 1
+fi
+
+# Copy documention to docs/
+ln -s "$(dirname "$(tail -n1 haddock_log)")" docs

.ci/docker/Dockerfile

@@ -0,0 +1,41 @@
+FROM ubuntu:focal
+
+ENV DEBIAN_FRONTEND=noninteractive LANG=C.UTF-8 LC_ALL=C.UTF-8 PATH=/opt/bin:/root/.ghcup/bin:$PATH
+
+ENV LATEST_STACK=linux-x86_64.tar.gz
+ENV STACK_DEPS="g++ gcc libc6-dev libffi-dev libgmp-dev make xz-utils zlib1g-dev git gnupg netbase"
+ARG GHC_DEPS="curl libc6-dev libgmp-dev pkg-config libnuma-dev build-essential"
+
+ENV GHC_VERSION=8.10.2
+ENV CABAL_VERSION=3.2.0.0
+
+ARG GHCUP_URL="https://downloads.haskell.org/~ghcup/x86_64-linux-ghcup"
+ARG GHCUP_BIN=/root/.ghcup/bin/ghcup
+
+# Install GHC + Cabal
+RUN apt-get update \
+ && apt-get install -y $GHC_DEPS curl \
+ && mkdir -p $(dirname $GHCUP_BIN) \
+ && curl $GHCUP_URL --output $GHCUP_BIN \
+ && chmod +x $GHCUP_BIN \
+ && ghcup upgrade \
+ && ghcup install ghc ${GHC_VERSION} \
+ && ghcup set ghc ${GHC_VERSION} \
+ && ghcup install cabal ${CABAL_VERSION} \
+ && ghcup set cabal ${CABAL_VERSION}
+
+# Install Stack
+RUN  apt-get update \
+  && apt-get -y install wget \
+  && apt-get -y install $STACK_DEPS \
+  && wget https://get.haskellstack.org/stable/$LATEST_STACK \
+  && tar xzf $LATEST_STACK && rm $LATEST_STACK \
+  && mv stack*/stack /usr/bin
+
+# Clash dependency
+RUN  apt-get update \
+  && apt-get -y install libtinfo-dev
+
+# Compression utils
+RUN  apt-get update \
+  && apt-get -y install tar zip zstd

.ci/docker/build-and-publish-docker-image.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+set -xeo pipefail
+
+REPO="docker.pkg.github.com/clash-lang/clash-protocols"
+NAME="focal-ghc-cabal-stack"
+DIR=$(dirname "$0")
+now=$(date +%F)
+
+docker build -t "${REPO}/${NAME}:$now" "$DIR"
+docker tag "${REPO}/${NAME}:$now" "${REPO}/${NAME}:latest"
+
+read -p "Push to GitHub? (y/N) " push
+
+if [[ $push =~ ^[Yy]$ ]]; then
+        docker push "${REPO}/${NAME}:$now"
+        docker push "${REPO}/${NAME}:latest"
+else
+        echo "Skipping push to container registry"
+fi

.ci/setup.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -xou pipefail
+
+grep \
+  -E ' $' -n -r . \
+  --include=*.{hs,hs-boot,sh,cabal,md,yml} \
+  --exclude-dir=dist-newstyle --exclude-dir=deps
+if [[ $? == 0 ]]; then
+    echo "EOL whitespace detected. See ^"
+    exit 1;
+fi
+
+set -e
+
+ghcup set ghc ${GHC_VERSION}
+ghcup set cabal ${CABAL_VERSION}
+
+cabal --version
+ghc --version
+
+# run new-update first to generate the cabal config file that we can then modify
+# retry 5 times, as hackage servers are not perfectly reliable
+NEXT_WAIT_TIME=0
+until cabal update || [ $NEXT_WAIT_TIME -eq 5 ]; do
+   sleep $(( NEXT_WAIT_TIME++ ))
+done

.ci/test_cabal.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+set -xeou pipefail
+
+cabal build all -fci
+cabal run test-library -fci --enable-tests
+cabal sdist

.ci/test_stack.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -xeou pipefail
+
+stack build
+stack test

.gitignore

@@ -0,0 +1,47 @@
+dist/
+dist-newstyle/
+.stack-work/
+cabal-dev
+/cabal.project.local
+.ghc.environment.*
+*.o
+*.o-boot
+*.hi
+*.hi-boot
+*.po
+*.po-boot
+*.p_o
+*.p_o-boot
+*.chi
+*.chs.h
+*.dyn_o
+*.dyn_o-boot
+*.dyn_hi
+*.dyn_hi-boot
+.virtualenv
+.hpc
+.hsenv
+.cabal-sandbox/
+cabal.sandbox.config
+cabal.config
+*.prof
+*.aux
+*.hp
+*.bin
+*.log
+*.tar.gz
+stack.yaml.lock
+
+*~
+*.DS_Store
+
+# IntelliJ
+/.idea
+*.iml
+
+# HDL directories often created during development cycle
+/vhdl
+/verilog
+/systemverilog
+
+log

.gitlab-ci.yml

@@ -0,0 +1,47 @@
+.common:
+  image: docker.pkg.github.com/clash-lang/stack-templates/focal-ghc-cabal-stack:2020-11-28
+  timeout: 1 hour
+  retry:
+    max: 2
+    when:
+      - runner_system_failure
+      - stuck_or_timeout_failure
+  cache:
+    key: $CI_JOB_NAME
+    paths:
+      - cache.tar.zstd
+  tags:
+    - local
+  before_script:
+    - export THREADS=$(nproc)
+    - export CABAL_JOBS=$(nproc)
+    - tar -xf cache.tar.zstd -C / || true
+    - .ci/setup.sh
+    - export
+  after_script:
+    - tar -cf - $(ls -d /root/.cabal /root/.stack /nix || true) | zstd -T0 -3 > cache.tar.zstd
+
+.common-810:
+  extends: .common
+  variables:
+    GHC_VERSION: "8.10.2"
+    CABAL_VERSION: "3.2.0.0"
+
+haddock:
+  extends: .common-810
+  artifacts:
+    paths:
+      - docs/*
+    expire_in: 1 month
+  script:
+    - .ci/build_docs.sh
+
+cabal-8.10.2:
+  extends: .common-810
+  script:
+    - .ci/test_cabal.sh
+
+stack:
+  extends: .common
+  script:
+    - .ci/test_stack.sh

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "deps/circuit-notation"]
+	path = deps/circuit-notation
+	url = https://github.com/martijnbastiaan/circuit-notation.git

.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+    "files.exclude": {
+        "**/*.dyn_hi": true,
+        "**/*.dyn_o": true,
+        "**/*.hi": true,
+        "**/*.o": true,
+        "dist-newstyle": true,
+        ".stack-work": true,
+        ".ghc.environment.*": true
+    },
+    "files.trimTrailingWhitespace": true,
+    "files.insertFinalNewline": true,
+    "editor.tabSize": 2
+}

LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2020, Martijn Bastiaan
+              2020, QBayLogic B.V.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,23 @@
+# Clash Protocols
+
+## TODO
+
+0.1
+
+- [ ] README
+- [ ] Fix DSL plugin
+- [ ] Add more convenient functions: `fanin`, `roundrobin`, ..
+- [ ] Make `Dfs` base implementation instead of `Df` (performance / cleanliness)
+- [ ] Decide what to do with `Protocols.Ack`
+- [ ] Check dead doc links on CI
+- [ ] Upstream all changes to `circuit-notation` (where possible)
+- [ ] Add examples on how to use DSL plugin
+- [ ] Port and upstream examples `circuit-notation`
+- [ ] Blogpost introducing explaining the _why_ of `clash-protocols`
+
+0.2
+
+- [ ] AXI AMBA (in terms of `DfLike`!)
+- [ ] Test framework for "chunked" designs
+- [ ] Improve errors for multichannel tests
+- [ ] Investigate whether we can use injective type families for `SimulateType` and `ExpectType`

Setup.hs

@@ -0,0 +1,5 @@
+import Prelude
+import Distribution.Simple
+
+main :: IO ()
+main = defaultMain

cabal.project

@@ -0,0 +1,9 @@
+packages:
+  clash-protocols.cabal
+
+package clash-prelude
+  -- 'large-tuples' generates tuple instances for various classes up to the
+  -- GHC imposed maximum of 62 elements. This severely slows down compiling
+  -- Clash, and triggers Template Haskell bugs on Windows. Hence, we disable
+  -- it by default. This will be the default for Clash >=1.4.
+  flags: -large-tuples