From 6947f53eb79c5c8beda863e3df9e5a935e5915b2 Mon Sep 17 00:00:00 2001 From: Joshua Fife Date: Fri, 20 Aug 2021 12:15:44 -0600 Subject: [PATCH] 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