Created documentation and makefiles added proj-f to CI

Signed-off-by: Joshua Fife <jpfife17@gmail.com>

.github/scripts/build-examples.sh

@@ -47,7 +47,7 @@ shift
 
 examples="$@"
 if [ "$fpga_family" == "xc7" -a -z "$examples" ]; then
-    examples="counter picosoc litex litex_linux button_controller timer pulse_width_led"
+    examples="counter picosoc litex litex_linux button_controller timer pulse_width_led hello-a"
 elif [ "$fpga_family" == "eos-s3" -a -z "$examples" ]; then
     examples="counter"
 fi
@@ -83,6 +83,10 @@ if [ "$fpga_family" = "xc7" ]; then
                 ;;
             "timer")
                 snippets="${snippets} xc7/timer/README.rst:example-watch-basys3"
+
+            # Project F examples
+            "hello-a")
+                TARGET="arty_35" make -C projf-makefiles/hello/hello-arty/A
                 ;;
              *)
                 echo "ERROR: Unknown example name: $example" >&2

.github/scripts/build-projF.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+#
+# Copyright (C) 2020  The SymbiFlow Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+set -e
+
+CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+source ${CURRENT_DIR}/common.sh
+
+# -- validate input ----------------------------------------------------------
+
+function help() {
+   echo
+   echo "Build examples from the repository"
+   echo
+   echo "Syntax: $0 fpga_family [examples]..."
+   echo "Arguments:"
+   echo "  fpga_family  - A supported FPGA family"
+   echo "  examples     - A name of an available example from project F"
+   echo
+}
+
+if [[ ! $# -ge 1 ]]; then
+  echo "Invalid number of arguments!"
+  help
+  exit 1
+fi
+
+# -- tuttest -----------------------------------------------------------------
+
+fpga_family=$1
+shift
+
+examples="$@"
+if [ "$fpga_family" == "xc7" -a -z "$examples" ]; then
+    examples="hello-a"
+fi
+
+# activate conda and enter example dir
+
+snippets="docs/building-examples.rst:export-install-dir,fpga-fam-$fpga_family,conda-prep-env-$fpga_family,conda-act-env"
+
+# call tuttest to activate conda
+tuttest_exec ${snippets}
+
+# import project F
+tuttest_exec "docs/project-f.rst:import-projectf"
+
+# Xilinx 7-Series examples
+if [ "$fpga_family" = "xc7" ]; then
+    for example in $examples; do
+        case $example in
+            "hello-a")
+                TARGET="arty_35" make -C projf-makefiles/hello/hello-arty/A
+                ;;
+             *)
+                echo "ERROR: Unknown example name: $example" >&2
+                exit 1
+                ;;
+        esac
+    done
+fi

.github/workflows/sphinx-tuttest.yml

@@ -58,6 +58,7 @@ jobs:
           - {fpga-fam: "xc7",    os: "debian", os-version: "bullseye", example: "litex_linux"}
           - {fpga-fam: "xc7",    os: "debian", os-version: "sid",      example: "litex_linux"}
   
+
           - {fpga-fam: "xc7",    os: "ubuntu", os-version: "xenial",   example: "button_controller"}
           - {fpga-fam: "xc7",    os: "ubuntu", os-version: "bionic",   example: "button_controller"}
           - {fpga-fam: "xc7",    os: "ubuntu", os-version: "focal",    example: "button_controller"}
@@ -85,6 +86,15 @@ jobs:
           - {fpga-fam: "xc7",    os: "debian", os-version: "bullseye", example: "timer"}
           - {fpga-fam: "xc7",    os: "debian", os-version: "sid",      example: "timer"}
 
+          
+          - {fpga-fam: "xc7",    os: "ubuntu", os-version: "xenial",   example: "hello-a"}
+          - {fpga-fam: "xc7",    os: "ubuntu", os-version: "bionic",   example: "hello-a"}
+          - {fpga-fam: "xc7",    os: "ubuntu", os-version: "focal",    example: "hello-a"}
+          - {fpga-fam: "xc7",    os: "centos", os-version: "7",        example: "hello-a"}
+          - {fpga-fam: "xc7",    os: "centos", os-version: "8",        example: "hello-a"}
+          - {fpga-fam: "xc7",    os: "debian", os-version: "buster",   example: "hello-a"}
+          - {fpga-fam: "xc7",    os: "debian", os-version: "bullseye", example: "hello-a"}
+          - {fpga-fam: "xc7",    os: "debian", os-version: "sid",      example: "hello-a"}
     env:
       LANG: "en_US.UTF-8"
       DEBIAN_FRONTEND: "noninteractive"
@@ -114,6 +124,9 @@ jobs:
       - name: Build examples
         run: bash .github/scripts/build-examples.sh ${{matrix.fpga-fam}} ${{matrix.example}}
 
+      - name: Build Project F
+        run: bash .github/scripts/build-projF.sh ${{matrix-projF.fpga-fam}} ${{matrix-projF.example}}
+
       - uses: actions/upload-artifact@v2
         with:
           name: symbiflow-examples-bitstreams

docs/index.rst

@@ -39,3 +39,4 @@ currently targeting chips from multiple vendors, e.g.:
    personal-designs
    customizing-makefiles
    understanding-commands
+   project-f

docs/project-f.rst

@@ -0,0 +1,51 @@
+Running Project F designs in Symbiflow
+======================================
+
+.. warning::
+   Symbiflow does not currently support the MMCME2_BASE primitive--a key commponent in Project F's 
+   clock_gen_480p module and all designs involving video output. 
+   As such, all of the designs in project F that require a display (all designs in FPGA graphics) will
+   fail when run through the toolchain. Only the designs in 
+   `Hello Arty <https://github.com/projf/projf-explore/tree/master/hello/hello-arty>`_ are currently 
+   officially supported. To track the progress of the MMCME2_BASE see issue 
+   `#153 <https://github.com/SymbiFlow/symbiflow-examples/issues/153>`_ in symbiflow examples and 
+   issue `#2246 <https://github.com/SymbiFlow/symbiflow-arch-defs/issues/2246>`_ in arch-defs.
+   One user was able to successfully run most of the display designs in project F by replacing the
+   MMCM in clock_gen_480p.sv with a PLLE2_ADV. For details on that see issue 
+   `#180 <https://github.com/SymbiFlow/symbiflow-examples/issues/180>`_ in symbiflow-examples.
+
+Project F is an amazing repository containing many high quality FPGA example designs that show
+some of the more impressive things you can do with an FPGA. You can find detailed documentation on
+the designs and how they work on `the developers blog <https://projectf.io/sitemap/>`_. 
+
+To build the Designs in Project F using symbiflow, first ensure that you have installed the Project F
+submodule locally. Enter into the ``symbiflow-examples`` directory and run:
+
+.. code-block:: bash
+   :name: import-projectf
+
+   git submodule update --init --recursive 
+
+After installing the Submodules, you can run any supported design by calling its makefile:
+
+.. code-block:: bash
+
+   TARGET="<board type>" make -C projf-makefiles/<design module>/<design subset>/<design number or part name>
+
+For example, to build the first design in project F's hello ary designs:
+
+.. code-block:: bash
+
+   TARGET="arty_35" make -C projf-makefiles/hello/hello-arty/A
+
+To download the bitstream to the board navigate to the generated bitstream and run openocd. 
+For example to download the first design from hello arty:
+
+.. code-block:: bash
+
+   cd hello-build/A 
+   openocd -f ${INSTALL_DIR}/${FPGA_FAM}/conda/envs/${FPGA_FAM}/share/openocd/scripts/board/digilent_arty.cfg -c "init; pld load 0 top.bit; exit"
+
+
+
+

projf-makefiles/common.mk

@@ -0,0 +1,59 @@
+BOARD_BUILDDIR := ${BUILDDIR}/${SUBPROJECT}
+
+# Set board properties based on TARGET variable
+ifeq ($(TARGET),arty_35)
+  DEVICE := xc7a50t_test
+  BITSTREAM_DEVICE := artix7
+  PARTNAME := xc7a35tcsg324-1
+else ifeq ($(TARGET),arty_100)
+  DEVICE := xc7a100t_test
+  BITSTREAM_DEVICE := artix7
+  PARTNAME := xc7a100tcsg324-1
+else ifeq ($(TARGET),nexys4ddr)
+  DEVICE := xc7a100t_test
+  BITSTREAM_DEVICE := artix7
+  PARTNAME := xc7a100tcsg324-1
+else ifeq ($(TARGET),nexys_video)
+  DEVICE := xc7a200t_test
+  BITSTREAM_DEVICE := artix7
+  PARTNAME := xc7a200tsbg484-1
+else ifeq ($(TARGET),basys3)
+  DEVICE := xc7a50t_test
+  BITSTREAM_DEVICE := artix7
+  PARTNAME := xc7a35tcpg236-1
+else
+  $(error Unsupported board type)
+endif
+
+
+XDC_CMD := -x ${XDC}
+
+
+.DELETE_ON_ERROR:
+
+# Build design
+all: ${BOARD_BUILDDIR}/${TOP}.bit
+
+${BOARD_BUILDDIR}:
+	mkdir -p ${BOARD_BUILDDIR}
+
+${BOARD_BUILDDIR}/${TOP}.eblif: | ${BOARD_BUILDDIR}
+	cd ${BOARD_BUILDDIR} && symbiflow_synth -t ${TOP} -v ${SOURCES} -d ${BITSTREAM_DEVICE} -p ${PARTNAME} ${XDC_CMD} 2>&1 > /dev/null
+
+${BOARD_BUILDDIR}/${TOP}.net: ${BOARD_BUILDDIR}/${TOP}.eblif
+	cd ${BOARD_BUILDDIR} && symbiflow_pack -e ${TOP}.eblif -d ${DEVICE} 2>&1 > /dev/null
+
+${BOARD_BUILDDIR}/${TOP}.place: ${BOARD_BUILDDIR}/${TOP}.net
+	cd ${BOARD_BUILDDIR} && symbiflow_place -e ${TOP}.eblif -d ${DEVICE} -n ${TOP}.net -P ${PARTNAME} 2>&1 > /dev/null
+
+${BOARD_BUILDDIR}/${TOP}.route: ${BOARD_BUILDDIR}/${TOP}.place
+	cd ${BOARD_BUILDDIR} && symbiflow_route -e ${TOP}.eblif -d ${DEVICE} 2>&1 > /dev/null
+
+${BOARD_BUILDDIR}/${TOP}.fasm: ${BOARD_BUILDDIR}/${TOP}.route
+	cd ${BOARD_BUILDDIR} && symbiflow_write_fasm -e ${TOP}.eblif -d ${DEVICE}
+
+${BOARD_BUILDDIR}/${TOP}.bit: ${BOARD_BUILDDIR}/${TOP}.fasm
+	cd ${BOARD_BUILDDIR} && symbiflow_write_bitstream -d ${BITSTREAM_DEVICE} -f ${TOP}.fasm -p ${PARTNAME} -b ${TOP}.bit
+
+clean:
+	rm -rf ${BUILDDIR}

projf-makefiles/hello/hello-arty/A/Makefile

@@ -0,0 +1,12 @@
+current_dir := ${CURDIR}
+proj_f_dir := ${current_dir}/../../../../projf-explore/hello/hello-arty/A
+SUBPROJECT := A
+BUILDDIR := ${current_dir}/../../../../hello-build
+
+TOP := top
+SOURCES := ${proj_f_dir}/top.sv
+
+XDC := ${proj_f_dir}/arty.xdc
+
+
+include ${current_dir}/../../../common.mk