Merge pull request #258 from antmicro/umarcor/docs/structure
docs: use multiple toctrees with different captions
This commit is contained in:
Karol Gugala
GitHub
commit
8596ad80c6
|
|
@ -55,7 +55,7 @@ fi
|
|||
# activate conda and enter example dir
|
||||
activate_env="docs/building-examples.rst:export-install-dir,fpga-fam-$fpga_family,conda-prep-env-$fpga_family,conda-act-env"
|
||||
snippets="${activate_env},enter-dir-$fpga_family"
|
||||
additionalDesigns="${activate_env},enter-dir-$fpga_family,additional_examples"
|
||||
additionalDesigns="${activate_env},enter-dir-$fpga_family"
|
||||
|
||||
|
||||
# Xilinx 7-Series examples
|
||||
|
|
@ -80,7 +80,7 @@ if [ "$fpga_family" = "xc7" ]; then
|
|||
|
||||
#Additional examples:
|
||||
"button_controller")
|
||||
snippets="${additionalDesigns} xc7/additional_examples/button_controller/README.rst:example-debouncer-basys3"
|
||||
snippets="${additionalDesigns} xc7/additional_examples/button_controller/README.rst:additional-examples,example-debouncer-basys3"
|
||||
;;
|
||||
"pulse_width_led")
|
||||
snippets="${snippets} xc7/pulse_width_led/README.rst:example-pulse-arty-35t"
|
||||
|
|
|
|||
|
|
@ -45,4 +45,4 @@ fi
|
|||
fpga_family=$1
|
||||
os=$2
|
||||
|
||||
tuttest_exec docs/getting-f4pga.rst:install-reqs-$os,wget-conda,conda-install-dir,fpga-fam-$fpga_family,conda-setup,download-arch-def-$fpga_family
|
||||
tuttest_exec docs/getting.rst:install-reqs-$os,wget-conda,conda-install-dir,fpga-fam-$fpga_family,conda-setup,download-arch-def-$fpga_family
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
Additional Basys3 Examples
|
||||
==========================
|
||||
|
||||
You can find several other exciting designs for the basys3 board in the additional_examples directory:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: additional_examples
|
||||
|
||||
cd additional_examples
|
||||
|
|
@ -1,5 +1,7 @@
|
|||
.. _Building-Examples:
|
||||
|
||||
Building example designs
|
||||
========================
|
||||
########################
|
||||
|
||||
Before building any example, set the installation directory to match what you
|
||||
set it to earlier, for example:
|
||||
|
|
@ -74,7 +76,7 @@ Finally, enter your working Conda environment:
|
|||
|
||||
|
||||
Xilinx 7-Series
|
||||
---------------
|
||||
===============
|
||||
|
||||
Enter the directory that contains examples for Xilinx 7-Series FPGAs:
|
||||
|
||||
|
|
@ -99,24 +101,11 @@ Enter the directory that contains examples for Xilinx 7-Series FPGAs:
|
|||
:file: templates/example.jinja
|
||||
|
||||
.. jinja:: xc7_pulse_width_led
|
||||
:file: templates/example.jinja
|
||||
|
||||
|
||||
|
||||
Additional Examples
|
||||
-------------------
|
||||
|
||||
In addition to the designs we have gone over here, you can also find several other exciting designs
|
||||
for the basys3 board in the additional_examples directory:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: additional_examples
|
||||
|
||||
cd additional_examples
|
||||
:file: templates/example.jinja
|
||||
|
||||
|
||||
QuickLogic EOS S3
|
||||
-----------------
|
||||
=================
|
||||
|
||||
Enter the directory that contains examples for QuickLogic EOS S3:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,13 +1,12 @@
|
|||
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 how to do that.
|
||||
A powerful tool in creating your own designs is understanding how to generate your own Makefile to 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 F4PGA
|
||||
commands used by the common Makefile to build and compile designs take a look at the
|
||||
`Understanding Toolchain Commands <understanding-commands.html>`_ page.
|
||||
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 F4PGA commands used by the common Makefile to build and
|
||||
compile designs take a look at the :ref:`Understanding` page.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
@ -107,7 +106,7 @@ your design. The general syntax depends on whether you are using XDC files or a
|
|||
|
||||
|
||||
A Note on the example designs use of ifeq/else ifeq blocks
|
||||
-------------------------------------------------------------
|
||||
----------------------------------------------------------
|
||||
|
||||
If you look at the Makefiles from the example designs within F4PGA
|
||||
(i.e. counter test, Picosoc, etc.), you will find an ifeq else ifeq block. The following snippet
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
.. _Getting:
|
||||
|
||||
Getting F4PGA
|
||||
=============
|
||||
#############
|
||||
|
||||
This section describes how to install F4PGA and set up a fully working
|
||||
environment to later build example designs.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
=============
|
||||
|
||||
To be able to follow through this tutorial, install the following software:
|
||||
|
||||
|
|
@ -52,7 +54,7 @@ Next, clone the F4PGA examples repository and enter it:
|
|||
cd f4pga-examples
|
||||
|
||||
Toolchain installation
|
||||
----------------------
|
||||
======================
|
||||
|
||||
Now we are able to install the F4PGA toolchain. This procedure is divided
|
||||
into three steps:
|
||||
|
|
@ -62,7 +64,7 @@ into three steps:
|
|||
- downloading the architecture definitions and installing the toolchain.
|
||||
|
||||
Conda
|
||||
~~~~~
|
||||
-----
|
||||
|
||||
Download Conda installer script into the f4pga-examples directory:
|
||||
|
||||
|
|
@ -84,8 +86,8 @@ and so you will need to add some ``sudo`` commands to the instructions below.
|
|||
|
||||
export INSTALL_DIR=~/opt/f4pga
|
||||
|
||||
Toolchain
|
||||
~~~~~~~~~
|
||||
Setup and download assets
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Select your target FPGA family:
|
||||
|
||||
|
|
@ -139,11 +141,9 @@ Download architecture definitions:
|
|||
|
||||
If the above commands exited without errors, you have successfully installed and configured your working environment.
|
||||
|
||||
Build Example Designs
|
||||
---------------------
|
||||
.. IMPORTANT::
|
||||
With the toolchain installed, you are ready to build the example designs!
|
||||
Examples are provided in separated directories:
|
||||
|
||||
With the toolchain installed, you can build the example designs.
|
||||
The example designs are provided in separate directories:
|
||||
|
||||
* ``xc7`` directory for the Artix-7 devices
|
||||
* ``eos-s3`` directory for the EOS S3 devices
|
||||
* Subdir :ghsrc:`xc7` for the Artix-7 devices
|
||||
* Subdir :ghsrc:`eos-s3` for the EOS S3 devices
|
||||
|
|
@ -10,13 +10,12 @@ It currently focuses on the following FPGA families:
|
|||
|
||||
Follow this guide to:
|
||||
|
||||
- :doc:`install F4PGA <getting-f4pga>` and all of its dependencies,
|
||||
- :doc:`install F4PGA <getting>` and all of its dependencies,
|
||||
- :doc:`build <building-examples>` and :doc:`upload <running-examples>`
|
||||
example designs onto the devboard of your choice.
|
||||
- compile and run :doc:`your own designs<personal-designs>` using the F4PGA toolchain.
|
||||
- :doc:`customize the Makefile<customizing-makefiles>` for your own designs.
|
||||
- gain valuable information about `Understanding Toolchain Commands in F4PGA <understanding-commands.html>`_
|
||||
|
||||
- gain valuable information about :doc:`Understanding Toolchain Commands in F4PGA <understanding>`.
|
||||
|
||||
About F4PGA
|
||||
-----------
|
||||
|
|
@ -30,13 +29,24 @@ currently targeting chips from multiple vendors, e.g.:
|
|||
- QuickLogic EOS S3
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Sections
|
||||
|
||||
getting-f4pga
|
||||
getting
|
||||
understanding
|
||||
|
||||
.. toctree::
|
||||
:caption: Example designs
|
||||
|
||||
building-examples
|
||||
running-examples
|
||||
|
||||
.. toctree::
|
||||
:caption: Custom designs
|
||||
|
||||
personal-designs
|
||||
customizing-makefiles
|
||||
understanding-commands
|
||||
|
||||
.. toctree::
|
||||
:caption: Additional example designs
|
||||
|
||||
project-f
|
||||
basys3
|
||||
|
|
|
|||
|
|
@ -1,58 +1,59 @@
|
|||
Building Custom Designs
|
||||
========================
|
||||
.. _Building-Custom-Designs:
|
||||
|
||||
This section describes how to compile and download your own designs to an FPGA using only
|
||||
Building Custom Designs
|
||||
=======================
|
||||
|
||||
This section describes how to compile and download your own designs to an FPGA using only
|
||||
the F4PGA toolchain.
|
||||
|
||||
Before building any examples, you will need to first install the toolchain. To do this, follow the
|
||||
steps in `Getting F4PGA <getting-f4pga.html>`_. After you have downloaded the toolchain,
|
||||
follow the steps in `Building Examples <building-examples.html>`_ by seting the installation
|
||||
directory to match what you set it to earlier, assigning the path and source for
|
||||
your conda environment, and activating your env.
|
||||
Before building any examples, you will need to first install the toolchain. To do this, follow the steps in :ref:`Getting`.
|
||||
After you have downloaded the toolchain, follow the steps in :ref:`Building-Examples` by seting the installation
|
||||
directory to match what you set it to earlier, assigning the path and source for your conda environment, and activating
|
||||
your env.
|
||||
|
||||
Preparing Your Design
|
||||
----------------------
|
||||
Preparing Your Design
|
||||
---------------------
|
||||
|
||||
Building a design in F4PGA requires three parts: the HDL files for your design, a constraints
|
||||
file, and a Makefile. For simplicity, all three of these design files should be moved to a single
|
||||
directory. The location of the directory does not mater as long as the three design elements are all
|
||||
directory. The location of the directory does not mater as long as the three design elements are all
|
||||
within it.
|
||||
|
||||
HDL Files
|
||||
++++++++++
|
||||
+++++++++
|
||||
|
||||
F4PGA provides full support for Verilog. Some support for SystemVerilog HDL code is also
|
||||
provided, although more complicated designs written in SystemVerilog may not build properly under
|
||||
Yosys. 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, the top level module in your HDL
|
||||
code should be declared as ``module top (...``. Failure to do so will result in an error from
|
||||
symbiflow_synth stating something similar to ``ERROR: Module 'top' not found!`` If you are using
|
||||
your own makefiles or commands, you can specify your top level module name using the -t flag in
|
||||
``symbiflow_synth``.
|
||||
F4PGA provides full support for Verilog. Some support for SystemVerilog HDL code is also
|
||||
provided, although more complicated designs written in SystemVerilog may not build properly under
|
||||
Yosys. 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, the top level module in your HDL
|
||||
code should be declared as ``module top (...``. Failure to do so will result in an error from
|
||||
symbiflow_synth stating something similar to ``ERROR: Module 'top' not found!`` If you are using
|
||||
your own makefiles or commands, you can specify your top level module name using the -t flag in
|
||||
``symbiflow_synth``.
|
||||
|
||||
Constraint File
|
||||
++++++++++++++++
|
||||
+++++++++++++++
|
||||
|
||||
The F4PGA toolchain supports both .XDC and .PCF+.SDC formats for constraints.
|
||||
You can use XDC to define IOPAD, IOSETTINGS, and clock constraints. SDCs can be used to
|
||||
define clock constraints and PCFs can be used to define IOPAD constraints only. Use whichever
|
||||
The F4PGA toolchain supports both .XDC and .PCF+.SDC formats for constraints.
|
||||
You can use XDC to define IOPAD, IOSETTINGS, and clock constraints. SDCs can be used to
|
||||
define clock constraints and PCFs can be used to define IOPAD constraints only. Use whichever
|
||||
method you prefer and add your constraint file(s) to your design directory.
|
||||
|
||||
Note that if you use an XDC file as your constraint and neglect to include your own SDC, the
|
||||
Note that if you use an XDC file as your constraint and neglect to include your own SDC, the
|
||||
toolchain will automatically generate one to provide clock constraints to VTR.
|
||||
|
||||
|
||||
Makefile
|
||||
+++++++++
|
||||
++++++++
|
||||
|
||||
Visit the `Customizing Makefiles <customizing-makefiles.html>`_ page to learn how to make a simple
|
||||
Visit the `Customizing Makefiles <customizing-makefiles.html>`_ 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
|
||||
Building your personal projects
|
||||
-------------------------------
|
||||
|
||||
Before you begin building your design, navigate to the directory where you have stored your
|
||||
Before you begin building your design, navigate to the directory where you have stored your
|
||||
Makefile, HDL, and constraint files:
|
||||
|
||||
.. code-block:: bash
|
||||
|
|
@ -60,7 +61,7 @@ Makefile, HDL, and constraint files:
|
|||
|
||||
cd <path to your directory>
|
||||
|
||||
Then, depending on your board type run:
|
||||
Then, depending on your board type run:
|
||||
|
||||
.. tabs::
|
||||
|
||||
|
|
@ -91,7 +92,7 @@ Then, depending on your board type run:
|
|||
:name: example-counter-basys3-group
|
||||
|
||||
TARGET="basys3" make -C .
|
||||
|
||||
|
||||
.. group-tab:: Nexys Video
|
||||
|
||||
.. code-block:: bash
|
||||
|
|
@ -100,12 +101,12 @@ Then, depending on your board type run:
|
|||
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:
|
||||
|
||||
|
|
@ -113,7 +114,7 @@ If your design builds without error, the bitstream can be found in the following
|
|||
|
||||
cd build/<board>
|
||||
|
||||
Once you navigate to the directory containing the bitstream, use the following commands on the
|
||||
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. Make sure to change ``top.bit`` to the
|
||||
name you used for your top level module:
|
||||
|
||||
|
|
@ -123,20 +124,20 @@ name you used for your top level module:
|
|||
|
||||
|
||||
.. tip::
|
||||
Many of the commands needed to build a project are run multiple times with little to no
|
||||
variation. 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 Xilinx 7 series FPGA
|
||||
Many of the commands needed to build a project are run multiple times with little to no
|
||||
variation. 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 Xilinx 7 series FPGA
|
||||
every time, you could just add the following lines to your .bashrc file:
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
:name: bash-functions
|
||||
|
||||
symbi_bit() {
|
||||
symbi_bit() {
|
||||
#Creates and downloads the bitstream to Xilinx 7 series FPGA:
|
||||
openocd -f <Your install directory>/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 Xilinx-7 series you can simply type
|
||||
Now whenever you need to download a bitstream to the Xilinx-7 series you can simply type
|
||||
``symbi_bit`` into the terminal and hit enter.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
Understanding Toolchain Commands
|
||||
=================================
|
||||
.. _Understanding:
|
||||
|
||||
Understanding the flow
|
||||
======================
|
||||
|
||||
This section provides valuable information on how each of the commands used to compile and build
|
||||
designs in F4PGA work. It is especially helpful for debugging or for using methods
|
||||
Loading…
Reference in New Issue