From b6932ed300d0cbfe8de787706082cb497a736b61 Mon Sep 17 00:00:00 2001 From: Joshua Fife Date: Tue, 8 Jun 2021 20:45:35 -0600 Subject: [PATCH] Rough Makefile Instructions Signed-off-by: Joshua Fife --- docs/Understanding-Makefile.rst | 148 +++++++++++++++++++++++++++++++- docs/personal-designs.rst | 20 ++--- 2 files changed, 154 insertions(+), 14 deletions(-) diff --git a/docs/Understanding-Makefile.rst b/docs/Understanding-Makefile.rst index 3b8f23c..012ba6f 100644 --- a/docs/Understanding-Makefile.rst +++ b/docs/Understanding-Makefile.rst @@ -1,14 +1,14 @@ Understanding the Makefile in Symbiflow ========================================== -A key steep in creating your own designs is understanding how to use the Makefiles in symbiflow. This tutorial walks you through some of the key aspects of working with the Makefiles in symbiflow to allow for better debuging. +A key steep in creating your own designs is understanding how to use the Makefiles in symbiflow. This tutorial walks you through some of the key aspects of working with the Makefiles in symbiflow to allow for better debugging. Example -======== -To understand how the Makfiles within symbiflow are setup lets take a look at a more simple Makefile that will run the symbiflow counter test on the basys3 board. Highlighted lines within the code bellow are of particular intrest. +------- +To understand how the Makfiles within symbiflow are setup lets take a look at a more simple Makefile that will run the symbiflow counter test on the basys3 board. Highlighted lines within the code bellow are of particular interest and will change depending on your design and hardware. .. code-block:: bash :name: makefile-example - :emphasize-lines: 4, 5, 11, 12, 22 + :emphasize-lines: 4, 5, 9, 10 :linenos: mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST))) @@ -56,4 +56,144 @@ Lets go over the highlighted lines one by one and discuss their purpose. Adding HDL files to your design ---------------------------------- +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 design using the following syntax: + + .. code-block:: bash + :name: multi-file-example + := ${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 should replace line 4 in the makefile with: + + .. code-block:: bash + :name: wildcard-example + + VERILOG := ${current_dir}/*.v + + +As of this writing symbiflow only supports Verilog and SystemVerilog HDL. + +Setting the device constraints +------------------------------ +Line 5 in the example sets the device type for the project. Several different board types are supported and a listing of the commands for each board type follows: + +.. 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 + + +As shown on line 9 of the example makefile you will also need to define the part your FPGA uses. 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 +---------------- + +Line 10 shows how you can specify what the constraint files are for your design. The general syntax depends on wether you are using XDC files or a SDC+PCF pair: + +.. tabs:: + + .. group-tab:: XDC + + .. code-block:: bash + + XDC:=${current_dir}/ + + .. group-tab:: SDC+PCF + + .. code-block:: bash + + PCF := ${current_dir}/ + SDC := ${current_dir}/ + +Note that the lines 22, 25, 28, and 31 (.eblif, net, place, and route) may will need to change depending on if you use an XDC file or some combination of SDC, PCF and XDC. \ No newline at end of file diff --git a/docs/personal-designs.rst b/docs/personal-designs.rst index d87cbe2..839558b 100644 --- a/docs/personal-designs.rst +++ b/docs/personal-designs.rst @@ -51,26 +51,26 @@ Finally, enter your working Conda environment: Preparing Your Design ---------------------- -Building a design in symbiflow requires three simple parts, the HDL files for your design, a constraints file, and a Makefile. For simplisity, all three of these design parts should be moved to a single directory. +Building a design in symbiflow requires three simple parts, the HDL files for your design, a constraints file, and a Makefile. For simplicity, all three of these design parts should be moved to a single directory. HDL files ++++++++++ -Symbiflow provides support for both Varilog and systemVarilog HDL code. Use whichever methode you perfer and add your design files to the directory of choice. If you are using the provided Makefiles to build your design, your top level module should be declared as ``module top (...``. +Symbiflow provides support for both Verilog and SystemVerilog HDL code. Use whichever method you prefer and add your design files to the directory of choice. If you are using the provided Makefiles to build your design, your top level module should be declared as ``module top (...``. Constraint file ++++++++++++++++ -The Symbiflow toolchain suports both .XDC and .PCF+.SDC formates for constraint files. Use whichever methode you perfer and add your constraint file(s) to the design directory. +The Symbiflow tool chain supports both .XDC and .PCF+.SDC formats for constraint files. Use whichever method you prefer and add your constraint file(s) to the design directory. .. warning:: - In its current state, symbiflow-examples does not provide support for dictionaries within XDC files by default. To support this functionality you will need to use the `XDC-plugin `_ from ``symbiflow-yosys-plugins.`` Failure to install the plugin beffore attempting to use dictionaries within your XDC file may result in a faulty bitstream. + In its current state, symbiflow-examples does not provide support for dictionaries within XDC files by default. To support this functionality you will need to use the `XDC-plugin `_ from ``symbiflow-yosys-plugins.`` Failure to install the plugin before attempting to use dictionaries within your XDC file may result in a faulty bitstream. Makefile +++++++++ To learn about how the Makefiles in symbiflow work see the `Understanding the Makefile in Symbiflow `_ page. -If you have used varilog 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 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. Building your personal projects @@ -116,13 +116,13 @@ Then, depending on your board type run: -If your design builds withought error, the bitstream can be found in the following location: +If your design builds without error, the bitstream can be found in the following location: .. code-block:: bash cd build/ -Finaly, for **Arty and Basys3**, you can upload the design with: +Finally, for **Arty and Basys3**, you can upload the design with: .. code-block:: bash @@ -130,8 +130,8 @@ Finaly, for **Arty and Basys3**, you can upload the design with: .. tip:: - Many of the commands needed to build a project are run many times. You might consider adding a few aliases or even a few bash functions to your .bashrc file to save yourself some typing or repeated coppy/paste. - For example, instead of using the somwhat cumbersome command used to upload the bitsream to arty or basys3 every time, you could just add the following lines to your bashrc file: + Many of the commands needed to build a project are run many times. You might consider adding a few aliases or even a few bash functions to your .bashrc file to save yourself some typing or repeated copy/paste. + For example, instead of using the somewhat cumbersome command used to upload the bitstream to arty or basys3 every time, you could just add the following lines to your bashrc file: .. code-block:: bash :name: bash-functions @@ -141,5 +141,5 @@ Finaly, for **Arty and Basys3**, you can upload the design with: openocd -f /home/chem3000/opt/symbiflow/xc7/conda/envs/xc7/share/openocd/scripts/board/digilent_arty.cfg -c "init; pld load 0 top.bit; exit" } - Now whenever you need to download a bitstream to the arty or basysis you can simply type ``symbi_bit`` into the terminal and hit enter. + Now whenever you need to download a bitstream to the arty or basys you can simply type ``symbi_bit`` into the terminal and hit enter.