added proj-f to CI and updated makefiles

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

@@ -1,44 +1,51 @@
 Running Project F designs in Symbiflow
 ======================================
 
-.. note::
+.. 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 none of the designs in project F that require a display (all designs in FPGA graphics) will
-   currently work with the toolchain. Only the designs in 
-   `Hello Arty<https://github.com/projf/projf-explore/tree/master/hello/hello-arty>`_ are currently 
+   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.
+   `#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 `#---<>`_.
+   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/>`_. 
+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:
+submodule locally. Enter into the ``symbiflow-examples`` directory and run:
 
 .. code-block:: bash
+   :name: import-projectf
 
-   cd symbiflow-examples
-   git submodule update --init --recursive /////////////////////////////Check to ensure/////////
+   git submodule update --init --recursive 
 
 After installing the Submodules, you can run any supported design by calling its makefile:
 
 .. code-block:: bash
 
-   TARGET="arty_35" make -C projf-makefiles/<design module>/<design subset>/<design number> ///////////////Change wording/////////
+   TARGET="<board type>" make -C projf-makefiles/<design module>/<design subset>/<design number or part name>
 
-To download the bitstream to the board run:
+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"
 
-..code-block:: bash
 
-   make download projf-makefiles/<design module>/<design subset>/<design number>
 
-.. tip:: 
-   If you don't have access to an arty and arty VGA Pmod all of the designs in project F should work 
-   fine on a basys board as well. Simply change the XDC constraint files and your target to 
-   ``TARGET="basys3"``.
 

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

@@ -1,7 +1,7 @@
 current_dir := ${CURDIR}
 proj_f_dir := ${current_dir}/../../../../projf-explore/hello/hello-arty/A
 SUBPROJECT := A
-BUILDDIR := ${current_dir}/../hello-build
+BUILDDIR := ${current_dir}/../../../../hello-build
 
 TOP := top
 SOURCES := ${proj_f_dir}/top.sv