From 6947f53eb79c5c8beda863e3df9e5a935e5915b2 Mon Sep 17 00:00:00 2001 From: Joshua Fife Date: Fri, 20 Aug 2021 12:15:44 -0600 Subject: [PATCH 1/5] finished updating makefile instructions and modified makeifle names Signed-off-by: Joshua Fife --- common/{Makefile => Makefile.common} | 2 +- docs/customizing-makefiles.rst | 334 ++++-------------- docs/master_makefile/Makefile | 66 ---- docs/personal-designs.rst | 23 +- docs/understanding-commands.rst | 12 + .../button_controller/Makefile | 2 +- xc7/counter_test/Makefile | 2 +- xc7/linux_litex_demo/Makefile | 2 +- xc7/picosoc_demo/Makefile | 2 +- 9 files changed, 102 insertions(+), 343 deletions(-) rename common/{Makefile => Makefile.common} (98%) delete mode 100644 docs/master_makefile/Makefile diff --git a/common/Makefile b/common/Makefile.common similarity index 98% rename from common/Makefile rename to common/Makefile.common index 182fadc..2e66447 100644 --- a/common/Makefile +++ b/common/Makefile.common @@ -65,7 +65,7 @@ ${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 + cd ${BOARD_BUILDDIR} && symbiflow_write_bitstream -d ${BITSTREAM_DEVICE} -f ${TOP}.fasm -p ${PARTNAME} -b top.bit download: ${BOARD_BUILDDIR}/${TOP}.bit if [ $(TARGET)='arty_35' ]; then \ diff --git a/docs/customizing-makefiles.rst b/docs/customizing-makefiles.rst index 5e4acdf..9ce3eb9 100644 --- a/docs/customizing-makefiles.rst +++ b/docs/customizing-makefiles.rst @@ -2,121 +2,80 @@ Customizing the Makefiles ========================== A powerful tool in creating your own designs is understanding how to generate your own Makefile to -compile projects. This tutorial walks you through some of the key aspects of working with Makefiles -and explains how you can create Makefiles for your own designs. +compile projects. This tutorial walks you through how to do that. If you would like to use methods other than a Makefile to build and compile your designs (such as python or bash scripts) or if you would like to learn more about the various Symbiflow -commands used by the Makefile to build and compile designs take a look at the +commands used by the common Makefile to build and compile designs take a look at the `Understanding Toolchain Commands `_ page. Example ------- -Every example design in Symbiflow has its own Makefile. For example -`counter test `_, -`Linux Litex demo `_, -and `PicoSoC demo `_ -all have there own unique Makefiles for compiling and building respective designs. To understand -how to set up a Makefile in Symbiflow, lets take a look at a simple Makefile. The following code -is based on the Makefile within `counter test `_ -and has been modified slightly for simplicity. Highlighted lines within the code below are of -particular interest and will change depending on your specific design elements and hardware. -Lines that are not highlighted do not change from design to design and can be copy and pasted -into your own Makefile. +By including Symbiflow's provided Makefile.common in your designs, running the commands necessary for building +your personal projects is incredibly simple. All you have to do is run a few simple commands and set +a few variables. + +To download Symbiflows common.Makefile run the following command inside the directory containing your +build files: + +.. code-block:: bash + + wget https://raw.githubusercontent.com/SymbiFlow/symbiflow-examples/master/common/Makefile.common + +Then create a main makefile by running ``touch Makefile``. Add the following to the contents of the file. +Don't change the two highlighted lines unless you know what you are doing: .. code-block:: bash :name: makefile-example - :emphasize-lines: 3, 4, 5, 6, 9, 10, 22, 25, 28, 31 + :emphasize-lines: 1, 9 :linenos: - mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST))) - current_dir := $(patsubst %/,%,$(dir $(mkfile_path))) - TOP := top - VERILOG := ${current_dir}/counter.v - DEVICE := xc7a50t_test - BITSTREAM_DEVICE := artix7 - BUILDDIR := build + current_dir := ${CURDIR} + # TOP := + # SOURCES := ${current_dir}/ - PARTNAME := xc7a35tcpg236-1 - XDC := ${current_dir}/basys3.xdc - BOARD_BUILDDIR := ${BUILDDIR}/basys3 + # PCF := ${current_dir}/ + # SDC := ${current_dir}/ + # XDC := ${current_dir}/ + + include ${current_dir}/Makefile.common + +Lets talk briefly about each of the commands in the above makefile - .DELETE_ON_ERROR: +Adding HDL Sources and Specifying the Top Module +------------------------------------------------ - all: ${BOARD_BUILDDIR}/${TOP}.bit +:ref:`Line 2` in the Makefile shows how to define the name for your top level module. +For example, if your top module was named ``module switches ( ...`` then you would simply uncomment +line 3 and change the text in ``<>`` to ``TOP := switches``. - ${BOARD_BUILDDIR}: - mkdir -p ${BOARD_BUILDDIR} - - ${BOARD_BUILDDIR}/${TOP}.eblif: | ${BOARD_BUILDDIR} - cd ${BOARD_BUILDDIR} && symbiflow_synth -t ${TOP} -v ${VERILOG} -d ${BITSTREAM_DEVICE} -p ${PARTNAME} -x ${XDC} 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} - - -Adding HDL files to your design --------------------------------- - -:ref:`Line 3 ` in the Makefile shows how to define the name for your top level module. For example, if -your top module was named ``module switches ( ...`` then you would simply change line 3 to -``TOP := switches``. - -.. warning:: - - If you change the name of your top level module then the command you use to download the bitstream to - your board using ``openocd`` will need to change slightly from what is provided in the examples. For - instance, if you changed the top level module name to ``TOP := my_module_top`` then the openocd command - would change to: - - .. code-block:: bash - - openocd -f /xc7/conda/envs/xc7/share/openocd/scripts/board/digilent_arty.cfg -c "init; pld load 0 my_module_top.bit; exit" - - Note that the only part of the command that changes is ".bit;" - -:ref:`Line 4 ` in the Makefile shows how to add HDL files to the design. The general syntax is: -``:=${current_dir}/``. You can also add multiple HDL files to a +:ref:`Line 3` in the Makefile shows how to add HDL files to the design. The general +syntax is: ``SOURCES:=${current_dir}/``. You can also add multiple HDL files to a design using the following syntax: .. code-block:: bash :name: multi-file-example - := ${current_dir}/ \ - ${current_dir}/ \ - ${current_dir}/ \ - ${current_dir}/ \ - ... + SOURCES := ${current_dir}/ \ + ${current_dir}/ \ + ${current_dir}/ \ + ... + ${current_dir}/ \ + You could also use wildcards to collect all HDL file types of a specific extension and add them to your design. For example, if you wanted to add all verilog files within the current directory -to your design, you could replace line 4 in the Makefile with: +to your design, you could replace line 3 in the Makefile with: .. code-block:: bash :name: wildcard-example - VERILOG := ${current_dir}/*.v + SOURCES := ${current_dir}/*.v To include SystemVerilog HDL in your designs simply change the ``.v`` extension in the examples -above to a ``.sv``. You might also want to change the ``VERILOG`` bash variables throughout the -Makefile to ``SYSTEM_VERILOG`` to improve readability. +above to a ``.sv``. .. note:: @@ -124,113 +83,11 @@ Makefile to ``SYSTEM_VERILOG`` to improve readability. SystemVerilog can also be run through the toolchain but more complicated designs may not be fully supported. -Setting the Board Type and Part Name -------------------------------------- - -:ref:`Line 5 ` in the example Makefile defines the device fabric -for the board being used in the project. Several different device fabrics are -supported and a listing of the commands for each follow: - -.. tabs:: - - .. group-tab:: Arty_35T - - .. code-block:: bash - :name: example-counter-a35t-group - - DEVICE := xc7a50t_test - - .. group-tab:: Arty_100T - - .. code-block:: bash - :name: example-counter-a100t-group - - DEVICE := xc7a100t_test - - .. group-tab:: Nexus 4 DDR - - .. code-block:: bash - :name: example-counter-nexys4ddr-group - - DEVICE := xc7a100t_test - - .. group-tab:: Basys3 - - .. code-block:: bash - :name: example-counter-basys3-group - - DEVICE := xc7a50t_test - - .. group-tab:: Zybo Z7 - - .. code-block:: bash - :name: example-counter-zybo-group - - DEVICE := xc7z010_test - - .. group-tab:: Nexys Video - - .. code-block:: bash - :name: example-counter-nexys_video-group - - DEVICE := xc7a200t_test - -:ref:`Line 7 ` defines the family for your FPGA. For example basys3 and arty boards are from the artix7 -family while zybo boards are from the zynq7 series. - -As shown on :ref:`line 9 ` of the example Makefile, you will also need to define the specific FPGA part -number for your chip. To do this, you need to add the following line of code to your Makefile -depending on your hardware: - -.. tabs:: - - .. group-tab:: Arty_35T - - .. code-block:: bash - :name: example-part-a35t-group - - PARTNAME := xc7a35tcsg324-1 - - .. group-tab:: Arty_100T - - .. code-block:: bash - :name: example-part-a100t-group - - PARTNAME := xc7a100tcsg324-1 - - .. group-tab:: Nexus 4 DDR - - .. code-block:: bash - :name: example-part-nexys4ddr-group - - PARTNAME := xc7a100tcsg324-1 - - .. group-tab:: Basys3 - - .. code-block:: bash - :name: example-part-basys3-group - - PARTNAME := xc7a35tcpg236-1 - - .. group-tab:: Zybo Z7 - - .. code-block:: bash - :name: example-part-zybo-group - - PARTNAME := xc7z010clg400-1 - - .. group-tab:: Nexys Video - - .. code-block:: bash - :name: example-part-nexys_video-group - - PARTNAME := xc7a200tsbg484-1 - Constraint files ---------------- -:ref:`Line 10 ` shows how you can specify what constraint files are being used for your design. The +:ref:`Lines 5-7 ` show how you can specify what constraint files are being used for your design. The general syntax depends on whether you are using XDC files or a SDC+PCF pair: .. tabs:: @@ -248,52 +105,13 @@ general syntax depends on whether you are using XDC files or a SDC+PCF pair: PCF := ${current_dir}/ SDC := ${current_dir}/ -Note that the :ref:`lines 22, 25, 28, and 31 ` (.eblif, net, place, and route) will also need to change -depending on if you use an XDC file or some combination of SDC and PCF files. The following -snippets show the differences and the areas that will need to change: -.. tabs:: +.. note:: - .. group-tab:: XDC + :ref:`Line 1 ` calls a make function ``CURDIR`` which returns the absolute + path for the current directory. :ref:`Line 9 ` simply includes the path to the + common makefile. - .. code-block:: bash - :lineno-start: 21 - :emphasize-lines: 2 - - ${BOARD_BUILDDIR}/${TOP}.eblif: | ${BOARD_BUILDDIR} - cd ${BOARD_BUILDDIR} && symbiflow_synth -t ${TOP} -v ${VERILOG} -d ${BITSTREAM_DEVICE} -p ${PARTNAME} -x ${XDC} 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 - - .. group-tab:: SDC+PCF - - .. code-block:: bash - :lineno-start: 21 - :emphasize-lines: 5, 8, 11 - - ${BOARD_BUILDDIR}/${TOP}.eblif: | ${BOARD_BUILDDIR} - cd ${BOARD_BUILDDIR} && symbiflow_synth -t ${TOP} -v ${VERILOG} -d ${BITSTREAM_DEVICE} -p ${PARTNAME} - - ${BOARD_BUILDDIR}/${TOP}.net: ${BOARD_BUILDDIR}/${TOP}.eblif - cd ${BOARD_BUILDDIR} && symbiflow_pack -e ${TOP}.eblif -d ${DEVICE} -s ${SDC} - - ${BOARD_BUILDDIR}/${TOP}.place: ${BOARD_BUILDDIR}/${TOP}.net - cd ${BOARD_BUILDDIR} && symbiflow_place -e ${TOP}.eblif -d ${DEVICE} -p ${PCF} -n ${TOP}.net -P ${PARTNAME} -s ${SDC} 2>&1 > /dev/null - - ${BOARD_BUILDDIR}/${TOP}.route: ${BOARD_BUILDDIR}/${TOP}.place - cd ${BOARD_BUILDDIR} && symbiflow_route -e ${TOP}.eblif -d ${DEVICE} -s ${SDC} 2>&1 > /dev/null - - - -:ref:`Lines 33-37 ` (running ``symbiflow_write_fasm`` and ``symbiflow_write_bitstream``) typically do -not change within the Makefile from design to design. A Note on the example designs use of ifeq/else ifeq blocks ------------------------------------------------------------- @@ -305,60 +123,42 @@ is from lines 9-39 of `the Makefile from counter test ` in our example: +designs you could just specify the TARGET variable within your makefile like so: .. code-block:: bash - :name: device-partname-snippet + :emphasize-lines: 2 + :linenos: - DEVICE := xc7a50t_test + current_dir := ${CURDIR} + TARGET := basys3 + TOP := ${current_dir}/# put the name of your top module here + SOURCES := ${current_dir}/# put your HDL sources here + ... - PARTNAME := xc7a35tcpg236-1 - XDC := ${current_dir}/ - -If you plan on using multiple types of hardware for your designs, then it might be better to just -copy the if else block from one of the Symbiflow-examples. Note that you may need to change the -names for the XDC or PCF+SDC parameters to match the names you have used. Also remember that you -will need to set the TARGET variable before running make on your design. +By setting the ``TARGET`` variable within the Makefile itself, you don't even have to specify +the TARGET variable before calling make. You can just use ``make -C `` diff --git a/docs/master_makefile/Makefile b/docs/master_makefile/Makefile deleted file mode 100644 index 174b0ae..0000000 --- a/docs/master_makefile/Makefile +++ /dev/null @@ -1,66 +0,0 @@ -# This Makefile can be add to your design to compile projects using Verilog as an HDL, -# and an XDC as a constraint. You can also make changes to this file to build more specialized designs. -mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST))) -current_dir := $(patsubst %/,%,$(dir $(mkfile_path))) -TOP := top -VERILOG := ${current_dir}/*.v -DEVICE := xc7a50t_test -BITSTREAM_DEVICE := artix7 -BUILDDIR := build - -ifeq ($(TARGET),arty_35) - PARTNAME := xc7a35tcsg324-1 - BOARD_BUILDDIR := ${BUILDDIR}/arty_35 -else ifeq ($(TARGET),arty_100) - PARTNAME := xc7a100tcsg324-1 - DEVICE := xc7a100t_test - BOARD_BUILDDIR := ${BUILDDIR}/arty_100 -else ifeq ($(TARGET),nexys4ddr) - PARTNAME := xc7a100tcsg324-1 - DEVICE := xc7a100t_test - BOARD_BUILDDIR := ${BUILDDIR}/nexys4ddr -else ifeq ($(TARGET),zybo) - PARTNAME := xc7z010clg400-1 - DEVICE := xc7z010_test - BITSTREAM_DEVICE := zynq7 - BOARD_BUILDDIR := ${BUILDDIR}/zybo - VERILOG := ${current_dir}/*.v -else ifeq ($(TARGET),nexys_video) - PARTNAME := xc7a200tsbg484-1 - DEVICE := xc7a200t_test - BOARD_BUILDDIR := ${BUILDDIR}/nexys_video -else - PARTNAME := xc7a35tcpg236-1 - BOARD_BUILDDIR := ${BUILDDIR}/basys3 -endif - -XDC:=${current_dir}/*.xdc - -.DELETE_ON_ERROR: - - -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 ${VERILOG} -d ${BITSTREAM_DEVICE} -p ${PARTNAME} -x ${XDC} 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/docs/personal-designs.rst b/docs/personal-designs.rst index 767436c..1622e8e 100644 --- a/docs/personal-designs.rst +++ b/docs/personal-designs.rst @@ -45,11 +45,9 @@ toolchain will automatically generate one to provide clock constraints to VTR. Makefile +++++++++ -If you have used verilog as your HDL and an XDC as your constraint, you can add this -:download:`Makefile ` to your design directory instead of building your -own. If you have used a different HDL than verilog or have used a combination of PCF+SDC -constraint files, you can find instructions for how to modify the provided makefile or create -your own in the `Customizing Makefiles `_ page. +Visit the `Customizing Makefiles `_ page to learn how to make a simple +Makefile for your designs. After following the directions listed there return to this page to +finish building your custom design. Building your personal projects ------------------------------- @@ -93,6 +91,21 @@ Then, depending on your board type run: :name: example-counter-basys3-group TARGET="basys3" make -C . + + .. group-tab:: Nexys Video + + .. code-block:: bash + :name: example-counter-nexys_video-group + + TARGET="nexys_video" make -C counter_test + + .. group-tab:: Zybo Z7 + + .. code-block:: bash + :name: example-counter-zybo-group + + TARGET="zybo" make -C counter_test + If your design builds without error, the bitstream can be found in the following location: diff --git a/docs/understanding-commands.rst b/docs/understanding-commands.rst index b0d7bf4..6449093 100644 --- a/docs/understanding-commands.rst +++ b/docs/understanding-commands.rst @@ -170,6 +170,18 @@ Notice that the specification for the part number is a lowercase ``-p`` instead ``-P`` as in the placement step. Also note that the ``-d`` in write_bitstream defines the FPGA family instead of the fabric as in the write_fasm step. +.. warning:: + + If you change the name of the output for your bitstream to something other than top.bit then the + openocd command used in the examples would need to change to. For example if I used + ``-b my_module_top`` in symbiflow_write_bitstream then my openocd command would change to: + + .. code-block:: bash + + openocd -f /xc7/conda/envs/xc7/share/openocd/scripts/board/digilent_arty.cfg -c "init; pld load 0 my_module_top.bit; exit" + + Note that the only part of the command that changes is ".bit;" + The following example generates a bitstream file named example.bit for the basys3 board: .. code-block:: bash diff --git a/xc7/additional_examples/button_controller/Makefile b/xc7/additional_examples/button_controller/Makefile index 053276f..31cdfd2 100644 --- a/xc7/additional_examples/button_controller/Makefile +++ b/xc7/additional_examples/button_controller/Makefile @@ -5,4 +5,4 @@ SOURCES := ${current_dir}/*.sv XDC := ${current_dir}/basys3.xdc -include ${current_dir}/../../../common/Makefile +include ${current_dir}/../../../common/Makefile.common diff --git a/xc7/counter_test/Makefile b/xc7/counter_test/Makefile index df92f1f..5cdc07c 100644 --- a/xc7/counter_test/Makefile +++ b/xc7/counter_test/Makefile @@ -17,5 +17,5 @@ else XDC := ${current_dir}/basys3.xdc endif -include ${current_dir}/../../common/Makefile +include ${current_dir}/../../common/Makefile.common diff --git a/xc7/linux_litex_demo/Makefile b/xc7/linux_litex_demo/Makefile index 81f81b5..0365355 100644 --- a/xc7/linux_litex_demo/Makefile +++ b/xc7/linux_litex_demo/Makefile @@ -7,4 +7,4 @@ PCF := ${current_dir}/arty.pcf SDC := ${current_dir}/arty.sdc XDC := ${current_dir}/arty.xdc -include ${current_dir}/../../common/Makefile \ No newline at end of file +include ${current_dir}/../../common/Makefile.common \ No newline at end of file diff --git a/xc7/picosoc_demo/Makefile b/xc7/picosoc_demo/Makefile index c39fdf7..e8fd967 100644 --- a/xc7/picosoc_demo/Makefile +++ b/xc7/picosoc_demo/Makefile @@ -21,4 +21,4 @@ else PCF := ${current_dir}/basys3.pcf endif -include ${current_dir}/../../common/Makefile \ No newline at end of file +include ${current_dir}/../../common/Makefile.common \ No newline at end of file From 4a818ebf9aad6214ea3e584df9c132ed5d7a503c Mon Sep 17 00:00:00 2001 From: Joshua Fife Date: Wed, 1 Sep 2021 18:47:42 -0600 Subject: [PATCH 2/5] fixed documentation and makefiles. Renamed common makefile. Signed-off-by: Joshua Fife --- common/{Makefile.common => common.mk} | 2 +- docs/customizing-makefiles.rst | 33 ++++++++----------- docs/personal-designs.rst | 3 +- docs/understanding-commands.rst | 2 +- .../button_controller/Makefile | 2 +- xc7/counter_test/Makefile | 2 +- xc7/linux_litex_demo/Makefile | 2 +- xc7/picosoc_demo/Makefile | 2 +- xc7/pulse_width_led/Makefile | 2 +- xc7/timer/Makefile | 2 +- 10 files changed, 23 insertions(+), 29 deletions(-) rename common/{Makefile.common => common.mk} (98%) diff --git a/common/Makefile.common b/common/common.mk similarity index 98% rename from common/Makefile.common rename to common/common.mk index 2e66447..182fadc 100644 --- a/common/Makefile.common +++ b/common/common.mk @@ -65,7 +65,7 @@ ${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 + cd ${BOARD_BUILDDIR} && symbiflow_write_bitstream -d ${BITSTREAM_DEVICE} -f ${TOP}.fasm -p ${PARTNAME} -b ${TOP}.bit download: ${BOARD_BUILDDIR}/${TOP}.bit if [ $(TARGET)='arty_35' ]; then \ diff --git a/docs/customizing-makefiles.rst b/docs/customizing-makefiles.rst index 9ce3eb9..515cdd9 100644 --- a/docs/customizing-makefiles.rst +++ b/docs/customizing-makefiles.rst @@ -12,34 +12,27 @@ commands used by the common Makefile to build and compile designs take a look at Example ------- -By including Symbiflow's provided Makefile.common in your designs, running the commands necessary for building +By including Symbiflow's provided common Makefile in your designs, running the commands necessary for building your personal projects is incredibly simple. All you have to do is run a few simple commands and set a few variables. -To download Symbiflows common.Makefile run the following command inside the directory containing your -build files: - -.. code-block:: bash - - wget https://raw.githubusercontent.com/SymbiFlow/symbiflow-examples/master/common/Makefile.common - -Then create a main makefile by running ``touch Makefile``. Add the following to the contents of the file. -Don't change the two highlighted lines unless you know what you are doing: +Create a makefile for your project by running ``touch Makefile``, and add the following to the contents. .. code-block:: bash :name: makefile-example - :emphasize-lines: 1, 9 :linenos: current_dir := ${CURDIR} - # TOP := - # SOURCES := ${current_dir}/ + TOP := + SOURCES := ${current_dir}/ + + # Include your constraint file path(s) below. Use either an XDC file + # or a PCF+SDC pair. Don't use all three file types. + XDC := ${current_dir}/ + PCF := ${current_dir}/ + SDC := ${current_dir}/ - # PCF := ${current_dir}/ - # SDC := ${current_dir}/ - # XDC := ${current_dir}/ - - include ${current_dir}/Makefile.common + include /common/common.mk Lets talk briefly about each of the commands in the above makefile @@ -87,8 +80,8 @@ above to a ``.sv``. Constraint files ---------------- -:ref:`Lines 5-7 ` show how you can specify what constraint files are being used for your design. The -general syntax depends on whether you are using XDC files or a SDC+PCF pair: +:ref:`Lines 7-9 ` show how you can specify what constraint files are being used for +your design. The general syntax depends on whether you are using XDC files or a SDC+PCF pair: .. tabs:: diff --git a/docs/personal-designs.rst b/docs/personal-designs.rst index 1622e8e..f3fd57f 100644 --- a/docs/personal-designs.rst +++ b/docs/personal-designs.rst @@ -114,7 +114,8 @@ If your design builds without error, the bitstream can be found in the following cd build/ Once you navigate to the directory containing the bitstream, use the following commands on the -**Arty and Basys3** to upload the design to your board: +**Arty and Basys3** to upload the design to your board. Make sure to change ``top.bit`` to the +name you used for your top level module: .. code-block:: bash diff --git a/docs/understanding-commands.rst b/docs/understanding-commands.rst index 6449093..ca2fad9 100644 --- a/docs/understanding-commands.rst +++ b/docs/understanding-commands.rst @@ -173,7 +173,7 @@ family instead of the fabric as in the write_fasm step. .. warning:: If you change the name of the output for your bitstream to something other than top.bit then the - openocd command used in the examples would need to change to. For example if I used + openocd command used in the examples would need to change too. For example if I used ``-b my_module_top`` in symbiflow_write_bitstream then my openocd command would change to: .. code-block:: bash diff --git a/xc7/additional_examples/button_controller/Makefile b/xc7/additional_examples/button_controller/Makefile index 31cdfd2..8f54a1c 100644 --- a/xc7/additional_examples/button_controller/Makefile +++ b/xc7/additional_examples/button_controller/Makefile @@ -5,4 +5,4 @@ SOURCES := ${current_dir}/*.sv XDC := ${current_dir}/basys3.xdc -include ${current_dir}/../../../common/Makefile.common +include ${current_dir}/../../../common/common.mk diff --git a/xc7/counter_test/Makefile b/xc7/counter_test/Makefile index 5cdc07c..d022824 100644 --- a/xc7/counter_test/Makefile +++ b/xc7/counter_test/Makefile @@ -17,5 +17,5 @@ else XDC := ${current_dir}/basys3.xdc endif -include ${current_dir}/../../common/Makefile.common +include ${current_dir}/../../common/common.mk diff --git a/xc7/linux_litex_demo/Makefile b/xc7/linux_litex_demo/Makefile index 0365355..aa560eb 100644 --- a/xc7/linux_litex_demo/Makefile +++ b/xc7/linux_litex_demo/Makefile @@ -7,4 +7,4 @@ PCF := ${current_dir}/arty.pcf SDC := ${current_dir}/arty.sdc XDC := ${current_dir}/arty.xdc -include ${current_dir}/../../common/Makefile.common \ No newline at end of file +include ${current_dir}/../../common/common.mk \ No newline at end of file diff --git a/xc7/picosoc_demo/Makefile b/xc7/picosoc_demo/Makefile index e8fd967..8f28aef 100644 --- a/xc7/picosoc_demo/Makefile +++ b/xc7/picosoc_demo/Makefile @@ -21,4 +21,4 @@ else PCF := ${current_dir}/basys3.pcf endif -include ${current_dir}/../../common/Makefile.common \ No newline at end of file +include ${current_dir}/../../common/common.mk \ No newline at end of file diff --git a/xc7/pulse_width_led/Makefile b/xc7/pulse_width_led/Makefile index d4069df..4983f82 100644 --- a/xc7/pulse_width_led/Makefile +++ b/xc7/pulse_width_led/Makefile @@ -6,4 +6,4 @@ SOURCES += ${current_dir}/pulse_led.v XDC := ${current_dir}/arty_35.xdc -include ${current_dir}/../../common/Makefile \ No newline at end of file +include ${current_dir}/../../common/common.mk \ No newline at end of file diff --git a/xc7/timer/Makefile b/xc7/timer/Makefile index e022307..12b2960 100644 --- a/xc7/timer/Makefile +++ b/xc7/timer/Makefile @@ -5,4 +5,4 @@ SOURCES := ${current_dir}/*.sv XDC := ${current_dir}/basys3.xdc -include ${current_dir}/../../common/Makefile \ No newline at end of file +include ${current_dir}/../../common/common.mk \ No newline at end of file From 20d3fa8026c2131762c0c60d57194c21da5d1e4e Mon Sep 17 00:00:00 2001 From: Joshua Fife Date: Sat, 6 Nov 2021 14:51:45 -0600 Subject: [PATCH 3/5] added symplified download instructions Signed-off-by: Joshua Fife --- xc7/counter_test/README.rst | 4 ++-- xc7/linux_litex_demo/README.rst | 4 ++-- xc7/picosoc_demo/README.rst | 2 +- xc7/pulse_width_led/README.rst | 2 +- xc7/timer/README.rst | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/xc7/counter_test/README.rst b/xc7/counter_test/README.rst index 6d1545c..1b075ef 100644 --- a/xc7/counter_test/README.rst +++ b/xc7/counter_test/README.rst @@ -43,13 +43,13 @@ At completion, the bitstreams are located in the build directory: .. code-block:: bash - cd counter_test/build/ + counter_test/build/ Now, for **Arty and Basys3**, you can upload the design with: .. code-block:: bash - 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" + TARGET="" make download -C counter_test The result should be as follows: diff --git a/xc7/linux_litex_demo/README.rst b/xc7/linux_litex_demo/README.rst index 4f9359a..ad32ea9 100644 --- a/xc7/linux_litex_demo/README.rst +++ b/xc7/linux_litex_demo/README.rst @@ -22,13 +22,13 @@ At completion, the bitstreams are located in the build directory: .. code-block:: bash - cd linux_litex_demo/build/ + linux_litex_demo/build/ Now you can upload the design with: .. code-block:: bash - 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" + TARGET="" make download -C linux_litex_demo .. note:: diff --git a/xc7/picosoc_demo/README.rst b/xc7/picosoc_demo/README.rst index 7ae7cd1..7f5be83 100644 --- a/xc7/picosoc_demo/README.rst +++ b/xc7/picosoc_demo/README.rst @@ -36,7 +36,7 @@ Now you can upload the design with: .. code-block:: bash - 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" + TARGET="" make download -C picosoc_demo You should observe the following line in the OpenOCD output: diff --git a/xc7/pulse_width_led/README.rst b/xc7/pulse_width_led/README.rst index ee39c2c..880b067 100644 --- a/xc7/pulse_width_led/README.rst +++ b/xc7/pulse_width_led/README.rst @@ -22,7 +22,7 @@ Now, you can upload the design with: .. code-block:: bash - 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" + TARGET="arty_35" make download -C pulse_width_led After downloading the bitstream, you can experiment with and mix different amounts of red, green, and blue on RGB led 0 by toggling different switches and buttons on and off. From left to right: diff --git a/xc7/timer/README.rst b/xc7/timer/README.rst index 3e81195..ee7adb0 100644 --- a/xc7/timer/README.rst +++ b/xc7/timer/README.rst @@ -21,7 +21,7 @@ Now, you can upload the design with: .. code-block:: bash - 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" + TARGET="basys3" make download -C timer After downloading the bitstream you can start and stop the watch by toggling switch 0 on the board. Press the center button to reset the counter. The following gives a visual example: From 3bf66c55ec3d3929a40be3d88c4ba6d9e3ba73b4 Mon Sep 17 00:00:00 2001 From: Joshua Fife Date: Sat, 6 Nov 2021 14:56:32 -0600 Subject: [PATCH 4/5] fixed minor issues Signed-off-by: Joshua Fife --- xc7/pulse_width_led/README.rst | 2 +- xc7/timer/README.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/xc7/pulse_width_led/README.rst b/xc7/pulse_width_led/README.rst index 880b067..d681d3b 100644 --- a/xc7/pulse_width_led/README.rst +++ b/xc7/pulse_width_led/README.rst @@ -16,7 +16,7 @@ At completion, the bitstreams are located in the build directory: .. code-block:: bash - cd pulse_width_led/build/arty_35 + pulse_width_led/build/arty_35 Now, you can upload the design with: diff --git a/xc7/timer/README.rst b/xc7/timer/README.rst index ee7adb0..41d484b 100644 --- a/xc7/timer/README.rst +++ b/xc7/timer/README.rst @@ -15,7 +15,7 @@ At completion, the bitstream is located in the build directory: .. code-block:: bash - cd timer/build/basys3 + timer/build/basys3 Now, you can upload the design with: From 999e562eba7e700623ac947767645c135f42be44 Mon Sep 17 00:00:00 2001 From: Joshua Fife Date: Tue, 16 Nov 2021 08:52:36 -0700 Subject: [PATCH 5/5] Fixed makefiles to include common.mk Signed-off-by: Joshua Fife --- projf-makefiles/hello/hello-arty/A/Makefile | 2 +- projf-makefiles/hello/hello-arty/B/Makefile | 2 +- projf-makefiles/hello/hello-arty/C/Makefile | 2 +- projf-makefiles/hello/hello-arty/D/Makefile | 2 +- projf-makefiles/hello/hello-arty/E/Makefile | 2 +- projf-makefiles/hello/hello-arty/F/Makefile | 2 +- projf-makefiles/hello/hello-arty/G/Makefile | 2 +- projf-makefiles/hello/hello-arty/H/Makefile | 2 +- projf-makefiles/hello/hello-arty/I/Makefile | 2 +- projf-makefiles/hello/hello-arty/J/Makefile | 2 +- projf-makefiles/hello/hello-arty/K/Makefile | 2 +- projf-makefiles/hello/hello-arty/L/Makefile | 2 +- 12 files changed, 12 insertions(+), 12 deletions(-) diff --git a/projf-makefiles/hello/hello-arty/A/Makefile b/projf-makefiles/hello/hello-arty/A/Makefile index 4743e16..b8c2b44 100644 --- a/projf-makefiles/hello/hello-arty/A/Makefile +++ b/projf-makefiles/hello/hello-arty/A/Makefile @@ -5,4 +5,4 @@ TOP := top SOURCES := ${proj_f_dir}/top.sv XDC := ${proj_f_dir}/arty.xdc -include ${current_dir}/../../../../common/Makefile +include ${current_dir}/../../../../common/common.mk diff --git a/projf-makefiles/hello/hello-arty/B/Makefile b/projf-makefiles/hello/hello-arty/B/Makefile index b705668..5be7fda 100644 --- a/projf-makefiles/hello/hello-arty/B/Makefile +++ b/projf-makefiles/hello/hello-arty/B/Makefile @@ -5,4 +5,4 @@ TOP := top SOURCES := ${proj_f_dir}/top.sv XDC := ${proj_f_dir}/arty.xdc -include ${current_dir}/../../../../common/Makefile +include ${current_dir}/../../../../common/common.mk diff --git a/projf-makefiles/hello/hello-arty/C/Makefile b/projf-makefiles/hello/hello-arty/C/Makefile index eec3723..5b5f7a2 100644 --- a/projf-makefiles/hello/hello-arty/C/Makefile +++ b/projf-makefiles/hello/hello-arty/C/Makefile @@ -5,4 +5,4 @@ TOP := top SOURCES := ${proj_f_dir}/top.sv XDC := ${proj_f_dir}/arty.xdc -include ${current_dir}/../../../../common/Makefile +include ${current_dir}/../../../../common/common.mk diff --git a/projf-makefiles/hello/hello-arty/D/Makefile b/projf-makefiles/hello/hello-arty/D/Makefile index c28491e..baab427 100644 --- a/projf-makefiles/hello/hello-arty/D/Makefile +++ b/projf-makefiles/hello/hello-arty/D/Makefile @@ -5,4 +5,4 @@ TOP := top SOURCES := ${proj_f_dir}/top.sv XDC := ${proj_f_dir}/arty.xdc -include ${current_dir}/../../../../common/Makefile +include ${current_dir}/../../../../common/common.mk diff --git a/projf-makefiles/hello/hello-arty/E/Makefile b/projf-makefiles/hello/hello-arty/E/Makefile index 8e092a8..14f2999 100644 --- a/projf-makefiles/hello/hello-arty/E/Makefile +++ b/projf-makefiles/hello/hello-arty/E/Makefile @@ -5,4 +5,4 @@ TOP := top SOURCES := ${proj_f_dir}/top.sv XDC := ${proj_f_dir}/arty.xdc -include ${current_dir}/../../../../common/Makefile +include ${current_dir}/../../../../common/common.mk diff --git a/projf-makefiles/hello/hello-arty/F/Makefile b/projf-makefiles/hello/hello-arty/F/Makefile index c3b2abf..b608bd9 100644 --- a/projf-makefiles/hello/hello-arty/F/Makefile +++ b/projf-makefiles/hello/hello-arty/F/Makefile @@ -5,4 +5,4 @@ TOP := top SOURCES := ${proj_f_dir}/top.sv XDC := ${proj_f_dir}/arty.xdc -include ${current_dir}/../../../../common/Makefile +include ${current_dir}/../../../../common/common.mk diff --git a/projf-makefiles/hello/hello-arty/G/Makefile b/projf-makefiles/hello/hello-arty/G/Makefile index b608da0..26964ec 100644 --- a/projf-makefiles/hello/hello-arty/G/Makefile +++ b/projf-makefiles/hello/hello-arty/G/Makefile @@ -5,4 +5,4 @@ TOP := top SOURCES := ${proj_f_dir}/top.sv XDC := ${proj_f_dir}/arty.xdc -include ${current_dir}/../../../../common/Makefile +include ${current_dir}/../../../../common/common.mk diff --git a/projf-makefiles/hello/hello-arty/H/Makefile b/projf-makefiles/hello/hello-arty/H/Makefile index 1346ac8..9d86825 100644 --- a/projf-makefiles/hello/hello-arty/H/Makefile +++ b/projf-makefiles/hello/hello-arty/H/Makefile @@ -5,4 +5,4 @@ TOP := top SOURCES := ${proj_f_dir}/top.sv XDC := ${proj_f_dir}/arty.xdc -include ${current_dir}/../../../../common/Makefile +include ${current_dir}/../../../../common/common.mk diff --git a/projf-makefiles/hello/hello-arty/I/Makefile b/projf-makefiles/hello/hello-arty/I/Makefile index aed7b37..ef5db64 100644 --- a/projf-makefiles/hello/hello-arty/I/Makefile +++ b/projf-makefiles/hello/hello-arty/I/Makefile @@ -5,4 +5,4 @@ TOP := top SOURCES := ${proj_f_dir}/*.sv XDC := ${proj_f_dir}/arty.xdc -include ${current_dir}/../../../../common/Makefile +include ${current_dir}/../../../../common/common.mk diff --git a/projf-makefiles/hello/hello-arty/J/Makefile b/projf-makefiles/hello/hello-arty/J/Makefile index 594ab82..94c2a07 100644 --- a/projf-makefiles/hello/hello-arty/J/Makefile +++ b/projf-makefiles/hello/hello-arty/J/Makefile @@ -5,4 +5,4 @@ TOP := top SOURCES := ${proj_f_dir}/*.sv XDC := ${proj_f_dir}/arty.xdc -include ${current_dir}/../../../../common/Makefile +include ${current_dir}/../../../../common/common.mk diff --git a/projf-makefiles/hello/hello-arty/K/Makefile b/projf-makefiles/hello/hello-arty/K/Makefile index 577921d..474f520 100644 --- a/projf-makefiles/hello/hello-arty/K/Makefile +++ b/projf-makefiles/hello/hello-arty/K/Makefile @@ -5,4 +5,4 @@ TOP := top SOURCES := ${proj_f_dir}/*.sv XDC := ${proj_f_dir}/arty.xdc -include ${current_dir}/../../../../common/Makefile +include ${current_dir}/../../../../common/common.mk diff --git a/projf-makefiles/hello/hello-arty/L/Makefile b/projf-makefiles/hello/hello-arty/L/Makefile index 66206a7..b4e6804 100644 --- a/projf-makefiles/hello/hello-arty/L/Makefile +++ b/projf-makefiles/hello/hello-arty/L/Makefile @@ -5,4 +5,4 @@ TOP := top SOURCES := ${proj_f_dir}/*.sv XDC := ${proj_f_dir}/arty.xdc -include ${current_dir}/../../../../common/Makefile +include ${current_dir}/../../../../common/common.mk