2023 clean-up and update

.github/workflows/ci.yaml

@@ -0,0 +1,22 @@
+name: Async_FIFO
+on: [push]
+jobs:
+  Lint:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: brew install verilator
+      - run: ./flow.sh lint
+  Simulation:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: brew install verilator
+      - run: brew install icarus-verilog
+      - run: ./flow.sh sim
+  Synthesis:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: brew install yosys
+      - run: ./flow.sh syn

.gitignore

@@ -3,3 +3,6 @@
 *.lxt
 .DS_Store
 tags
+lint.log script src
+async_fifo_syn.v
+lint.log

README.md

@@ -1,5 +1,6 @@
 # Asynchronous dual clock FIFO
 
+![CI](https://github.com/dpretet/async_fifo/actions/workflows/ci.yaml/badge.svg?branch=master)
 [![GitHub issues](https://img.shields.io/github/issues/dpretet/async_fifo)](https://github.com/dpretet/async_fifo/issues)
 [![GitHub forks](https://img.shields.io/github/forks/dpretet/async_fifo)](https://github.com/dpretet/async_fifo/network)
 [![GitHub stars](https://img.shields.io/github/stars/dpretet/async_fifo)](https://github.com/dpretet/async_fifo/stargazers)
@@ -18,10 +19,24 @@ Design](http://www.sunburst-design.com/papers/CummingsSNUG2002SJ_FIFO1.pdf).
 
 The simulation testcases available use [Icarus Verilog](http://iverilog.icarus.com) and [SVUT](https://github.com/dpretet/svut) tool to run the tests.
 
-# Documentation
+The FIFO is fully functional and used in many successful project
+
+# Usage
+
+RTL sources are present in RTL folder under three flavors:
+- `rtl/async_fifo.v`: a basic asynchronous dual-clock FIFO
+- `rtl/async_bidir_fifo.v`: two instance of the first one into a single top level for full-duplex channel
+- `rtl/async_bidir_ramif_fifo.v`: same than previous but with external RAM
+
+The three FIFOs have a list file to get the associated fileset.
+
+The testbench in `sim/` provides an example about the instance and the configuration.
+
+All three top levels have the same parameters:
+- `DSIZE`: the size in bits of the datapath
+- `ASIZE`: the size in bits of the internal RAM address bus. This implies the FIFO can be configured only with power of 2 depth
+- `FALLTHROUGH`: allow to reduce the inner latency and propagate faster the data through the FIFO
 
-* [specification](doc/specification.rst)
-* [testplan](doc/testplan.rst)
 
 # License
 

async_fifo.core

@@ -5,14 +5,11 @@ name : ::async_fifo:1.1.0-r1
 filesets:
   rtl:
     files:
-      - src/vlog/fifomem_dp.v
       - src/vlog/sync_r2w.v
-      - src/vlog/async_bidir_fifo.v
       - src/vlog/rptr_empty.v
       - src/vlog/sync_w2r.v
       - src/vlog/wptr_full.v
       - src/vlog/fifo_2mem.v
-      - src/vlog/async_bidir_ramif_fifo.v
       - src/vlog/async_fifo.v
       - src/vlog/sync_ptr.v
     file_type : verilogSource

doc/testplan.rst

@@ -13,39 +13,34 @@ A first focus is put in write vs read frequency relation:
 1. Test the same clock frequency on both sides. Phases can be equal or not.
 
 2. Test slower clock on write side
-
-    * clock can be close to read frequency, but slower
-    * clock can be very regarding read frequency
+    - clock can be close to read frequency, but slower
+    - clock can be very regarding read frequency
 
 3. Test higher clock on write side
-
-    * clock can be close to read frequency, but higher
-    * clock can be very high regarding read frequency
+    - clock can be close to read frequency, but higher
+    - clock can be very high regarding read frequency
 
 Read/Write enable control assertion
 -----------------------------------
 
 A second focus is put on read/write enable assertion:
 
 1. Read enable is always enable, unless empty = 1
-
-    * Write enable is always asserted, data are not corrupted
-    * Write enable can be occasionaly asserted, data are not corrupted
+    - Write enable is always asserted, data are not corrupted
+    - Write enable can be occasionaly asserted, data are not corrupted
 
 2. Write enable is always enable, unless full = 1
-
-    * Read enable is always asserted, data are not corrupted
-    * Read enable can be occasionaly asserted, data are not corrupted
+    - Read enable is always asserted, data are not corrupted
+    - Read enable can be occasionaly asserted, data are not corrupted
 
 3. Read and Write enable can be occasionaly asserted
-
-    * Assertion frequency (either read or write) is periodic (1/2, 1/3, 1/2, ...)
-    * Assertion frequecy is (pseudo) random
+    - Assertion frequency (either read or write) is periodic (1/2, 1/3, 1/2, ...)
+    - Assertion frequecy is (pseudo) random
 
 Test coverage
 -------------
 
-To ensure a wide feature feature coverage is performed, both clock frequency scale and 
-read/write enable assertions have to be tested together. Big range over higher frequency 
-scale factor doesn't have to considered. Only few conbinations can be tested for
+To ensure a wide feature feature coverage is performed, both clock frequency scale and
+read/write enable assertions have to be tested together. Big range over higher frequency
+scale factor doesn't have to considered. Only few combinations can be tested for
 good confidence on the IP behavior.

flow.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+
+# -e: exit if one command fails
+# -u: treat unset variable as an error
+# -f: disable filename expansion upon seeing *, ?, ...
+# -o pipefail: causes a pipeline to fail if any command fails
+set -e -o pipefail
+
+# Current script path; doesn't support symlink
+FIFO_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+
+
+# Bash color codes
+Red='\033[0;31m'
+Green='\033[0;32m'
+Yellow='\033[0;33m'
+Blue='\033[0;34m'
+# Reset
+NC='\033[0m'
+
+function printerror {
+    echo -e "${Red}ERROR: ${1}${NC}"
+}
+
+function printwarning {
+    echo -e "${Yellow}WARNING: ${1}${NC}"
+}
+
+function printinfo {
+    echo -e "${Blue}INFO: ${1}${NC}"
+}
+
+function printsuccess {
+    echo -e "${Green}SUCCESS: ${1}${NC}"
+}
+
+help() {
+    echo -e "${Blue}"
+    echo ""
+    echo "NAME"
+    echo ""
+    echo "      Async FIFO Flow"
+    echo ""
+    echo "SYNOPSIS"
+    echo ""
+    echo "      ./flow.sh -h"
+    echo ""
+    echo "      ./flow.sh help"
+    echo ""
+    echo "      ./flow.sh syn"
+    echo ""
+    echo "      ./flow.sh sim"
+    echo ""
+    echo "DESCRIPTION"
+    echo ""
+    echo "      This flow handles the different operations available"
+    echo ""
+    echo "      ./flow.sh help|-h"
+    echo ""
+    echo "      Print the help menu"
+    echo ""
+    echo "      ./flow.sh syn"
+    echo ""
+    echo "      Launch the synthesis script relying on Yosys"
+    echo ""
+    echo "      ./flow.sh sim"
+    echo -e "${NC}"
+}
+
+
+run_sims() {
+	printinfo "Start simulation"
+	cd "$FIFO_DIR"/sim
+	svutRun -f files.f -test async_fifo_unit_test.sv -sim icarus
+	return $?
+}
+
+run_syn() {
+	printinfo "Start synthesis"
+	cd "$FIFO_DIR/syn"
+	./syn_asic.sh
+	return $?
+}
+
+
+run_lint() {
+	set +e
+
+	printinfo "Start lint"
+	verilator --lint-only +1800-2017ext+sv \
+		-Wall -Wpedantic \
+		-Wno-VARHIDDEN \
+		-Wno-PINCONNECTEMPTY \
+		-Wno-PINMISSING \
+		./rtl/async_fifo.v \
+		./rtl/fifomem.v \
+		./rtl/rptr_empty.v \
+		./rtl/sync_r2w.v \
+		./rtl/sync_w2r.v \
+		./rtl/wptr_full.v \
+		--top-module async_fifo 2> lint.log
+
+	set -e
+
+	ec=$(grep -c "%Error:" lint.log)
+
+	if [[ $ec -gt 1 ]]; then
+		printerror "Lint failed, check ./lint.log for further details"
+		return 1
+	else
+		printsuccess "Lint ran successfully"
+		return 0
+	fi
+
+}
+
+check_setup() {
+
+    source script/setup.sh
+
+    if [[ ! $(type iverilog) ]]; then
+        printerror "Icarus-Verilog is not installed"
+        exit 1
+    fi
+    if [[ ! $(type verilator) ]]; then
+        printerror "Verilator is not installed"
+        exit 1
+    fi
+}
+
+
+main() {
+
+    echo ""
+    printinfo "Start Aync FIFO Flow"
+
+    # If no argument provided, preint help and exit
+    if [[ $# -eq 0 ]]; then
+        help
+        exit 1
+    fi
+
+    # Print help
+    if [[ $1 == "-h" || $1 == "help" ]]; then
+        help
+        exit 0
+    fi
+
+    if [[ $1 == "lint" ]]; then
+		run_lint
+		exit $?
+    fi
+
+    if [[ $1 == "sim" ]]; then
+        check_setup
+		run_sims
+        exit $?
+    fi
+
+    if [[ $1 == "syn" ]]; then
+		run_syn
+        return $?
+    fi
+}
+
+
+main "$@"

rtl/async_bidir_fifo.list

@@ -0,0 +1,8 @@
+async_bidir_fifo.v
+fifomem.v
+fifomem_dp.v
+rptr_empty.v
+sync_ptr.v
+sync_r2w.v
+sync_w2r.v
+wptr_full.v

rtl/async_bidir_ramif_fifo.list

@@ -0,0 +1,8 @@
+async_bidir_ramif_fifo.v
+fifomem.v
+fifomem_dp.v
+rptr_empty.v
+sync_ptr.v
+sync_r2w.v
+sync_w2r.v
+wptr_full.v

rtl/async_fifo.list

@@ -0,0 +1,9 @@
+async_fifo.v
+fifomem.v
+fifomem_dp.v
+hdl.list
+rptr_empty.v
+sync_ptr.v
+sync_r2w.v
+sync_w2r.v
+wptr_full.v