From 15e85e390c377fd3784f1966d4f377d82358ac14 Mon Sep 17 00:00:00 2001 From: Joshua Fife Date: Fri, 27 Aug 2021 10:53:59 -0600 Subject: [PATCH] Created documentation and makefiles added proj-f to CI Signed-off-by: Joshua Fife --- .github/scripts/build-examples.sh | 6 +- .github/scripts/build-projF.sh | 76 +++++++++++++++++++++ .github/workflows/sphinx-tuttest.yml | 13 ++++ docs/index.rst | 1 + docs/project-f.rst | 51 ++++++++++++++ projf-makefiles/common.mk | 59 ++++++++++++++++ projf-makefiles/hello/hello-arty/A/Makefile | 12 ++++ 7 files changed, 217 insertions(+), 1 deletion(-) create mode 100755 .github/scripts/build-projF.sh create mode 100644 docs/project-f.rst create mode 100644 projf-makefiles/common.mk create mode 100644 projf-makefiles/hello/hello-arty/A/Makefile diff --git a/.github/scripts/build-examples.sh b/.github/scripts/build-examples.sh index 49cfec44..353b55db 100755 --- a/.github/scripts/build-examples.sh +++ b/.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 diff --git a/.github/scripts/build-projF.sh b/.github/scripts/build-projF.sh new file mode 100755 index 00000000..2cfec0b0 --- /dev/null +++ b/.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 diff --git a/.github/workflows/sphinx-tuttest.yml b/.github/workflows/sphinx-tuttest.yml index 10532e76..bf8a0f03 100644 --- a/.github/workflows/sphinx-tuttest.yml +++ b/.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 diff --git a/docs/index.rst b/docs/index.rst index f3685569..dc4521c0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,3 +39,4 @@ currently targeting chips from multiple vendors, e.g.: personal-designs customizing-makefiles understanding-commands + project-f diff --git a/docs/project-f.rst b/docs/project-f.rst new file mode 100644 index 00000000..e6c7829a --- /dev/null +++ b/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 `_ are currently + officially supported. To track the progress of the MMCME2_BASE see issue + `#153 `_ in symbiflow examples and + issue `#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 `_ 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 `_. + +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="" make -C projf-makefiles/// + +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" + + + + diff --git a/projf-makefiles/common.mk b/projf-makefiles/common.mk new file mode 100644 index 00000000..d861dfcf --- /dev/null +++ b/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} \ No newline at end of file diff --git a/projf-makefiles/hello/hello-arty/A/Makefile b/projf-makefiles/hello/hello-arty/A/Makefile new file mode 100644 index 00000000..dfa2af16 --- /dev/null +++ b/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 \ No newline at end of file