Hardware
/
f4pga-examples
mirror of https://github.com/chipsalliance/f4pga-examples.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: use extlinks instead of raw refs 

Signed-off-by: Unai Martinez-Corral <umartinezcorral@antmicro.com>
This commit is contained in:
Unai Martinez-Corral 2022-02-13 18:56:16 +01:00
parent 8ad41a5be3
commit 289f92c004
4 changed files with 58 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/customizing-makefiles.rst
View File

@ -4,19 +4,19 @@ 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.
If you would like to use methods other than a Makefile to build and compile your designs
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.
Example
Example
-------
By including F4PGA's provided common Makefile in your designs, running the commands necessary for building
By including F4PGA'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.
a few variables.
Create a makefile for your project by running ``touch Makefile``, and add the following to the contents.
Create a makefile for your project by running ``touch Makefile``, and add the following to the contents.
.. code-block:: bash
:name: makefile-example
@ -25,8 +25,8 @@ Create a makefile for your project by running ``touch Makefile``, and add the fo
current_dir := ${CURDIR}
TOP := <put the name of your top module here>
SOURCES := ${current_dir}/<put your HDL sources here>
# Include your constraint file path(s) below. Use either an XDC file
# 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}/<name of your pcf file if applicable>
PCF := ${current_dir}/<name of your xdc file if applicable>
@ -40,14 +40,14 @@ Lets talk briefly about each of the commands in the above makefile
Adding HDL Sources and Specifying the Top Module
------------------------------------------------
:ref:`Line 2<makefile-example>` 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
:ref:`Line 2<makefile-example>` 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``.
:ref:`Line 3<makefile-example>` in the Makefile shows how to add HDL files to the design. The general
syntax is: ``SOURCES:=${current_dir}/<your HDL file path>``. You can also add multiple HDL files to a
:ref:`Line 3<makefile-example>` in the Makefile shows how to add HDL files to the design. The general
syntax is: ``SOURCES:=${current_dir}/<your HDL file path>``. You can also add multiple HDL files to a
design using the following syntax:
.. code-block:: bash
:name: multi-file-example
@ -58,35 +58,35 @@ design using the following syntax:
${current_dir}/<HDL file n> \
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
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 3 in the Makefile with:
.. code-block:: bash
:name: wildcard-example
SOURCES := ${current_dir}/*.v
To include SystemVerilog HDL in your designs simply change the ``.v`` extension in the examples
To include SystemVerilog HDL in your designs simply change the ``.v`` extension in the examples
above to a ``.sv``.
.. note::
As of this writing, F4PGAw only offers full support for Verilog by default.
SystemVerilog can also be run through the toolchain but more complicated
designs may not be fully supported.
As of this writing, F4PGA only offers full support for Verilog by default.
SystemVerilog can also be run through the toolchain but more complicated
designs may not be fully supported.
Constraint files
----------------
:ref:`Lines 7-9 <makefile-example>` show how you can specify what constraint files are being used for
:ref:`Lines 7-9 <makefile-example>` 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::
.. group-tab:: XDC
.. code-block:: bash
XDC := ${current_dir}/<name of XDC file>
@ -99,19 +99,19 @@ your design. The general syntax depends on whether you are using XDC files or a
SDC := ${current_dir}/<name of SDC file>
.. note::
.. note::
:ref:`Line 1 <makefile-example>` calls a make function ``CURDIR`` which returns the absolute
path for the current directory. :ref:`Line 9 <makefile-example>` simply includes the path to the
common makefile.
path for the current directory. :ref:`Line 9 <makefile-example>` simply includes the path to the
common makefile.
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
is from lines 9-39 of `the Makefile from counter test <https://github.com/chipsalliance/f4pga-examples/blob/master/xc7/counter_test/Makefile>`_:
(i.e. counter test, Picosoc, etc.), you will find an ifeq else ifeq block. The following snippet
is from lines 9-39 of :gh:`the Makefile from counter test <chipsalliance/f4pga-examples/blob/master/xc7/counter_test/Makefile>`:
.. code-block:: bash
@ -133,13 +133,13 @@ is from lines 9-39 of `the Makefile from counter test <https://github.com/chipsa
XDC := ${current_dir}/basys3.xdc
endif
This snippet of code is an if else block used to set device specific constraints (i.e. ``basys3.xdc``,
``nexys_video.xdc``). The code block determines what type of hardware is being used based upon a
TARGET variable which is assumed to be defined before running make. For example, you may recall
running ``TARGET="<board type>" make -C counter_test`` before building the counter test example.
This command sets the TARGET variable to the type of hardware you are using.
This snippet of code is an if else block used to set device specific constraints (i.e. ``basys3.xdc``,
``nexys_video.xdc``). The code block determines what type of hardware is being used based upon a
TARGET variable which is assumed to be defined before running make. For example, you may recall
running ``TARGET="<board type>" make -C counter_test`` before building the counter test example.
This command sets the TARGET variable to the type of hardware you are using.
The if else block is completely optional. If you are only using one type of hardware for your
The if else block is completely optional. If you are only using one type of hardware for your
designs you could just specify the TARGET variable within your makefile like so:
.. code-block:: bash
@ -152,6 +152,6 @@ designs you could just specify the TARGET variable within your makefile like so:
SOURCES := ${current_dir}/# put your HDL sources here
...
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 <path to directory containing
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 <path to directory containing
your design>``

6
docs/index.rst
View File

@ -1,9 +1,9 @@
Welcome to F4PGA examples!
==========================
This guide explains how to get started with F4PGA and build example designs
from the `F4PGA Examples <https://github.com/chipsalliance/f4pga-examples>`_
GitHub repository. It currently focuses on the following FPGA families:
This guide explains how to get started with F4PGA and build example designs from the :gh:`F4PGA Examples <chipsalliance/f4pga-examples>`
GitHub repository.
It currently focuses on the following FPGA families:
- Artix-7 from Xilinx,
- EOS S3 from QuickLogic.

30
docs/project-f.rst
View File

@ -2,21 +2,19 @@ Running Project F designs in F4PGA
==================================
.. warning::
F4PGA 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 <https://github.com/projf/projf-explore/tree/master/hello/hello-arty>`_ are currently
officially supported. To track the progress of the MMCME2_BASE see issue
`#153 <https://github.com/chipsalliance/f4pga-examples/issues/153>`_ in f4pga examples and
issue `#2246 <https://github.com/f4pga/f4pga-arch-defs/issues/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 <https://github.com/chipsalliance/f4pga-examples/issues/180>`_ in f4pga-examples.
F4PGA 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 :gh:`Hello Arty <projf/projf-explore/tree/master/hello/hello-arty>` are
currently officially supported.
To track the progress of the MMCME2_BASE see :ghissue:`153` and issue :gh:`chipsalliance/f4pga-arch-defs#2246 <chipsalliance/f4pga-arch-defs/issues/2246>`.
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 :ghissue:`180` in f4pga-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 <https://projectf.io/sitemap/>`_.
the designs and how they work on `the developers blog <https://projectf.io/sitemap/>`_.
To build the Designs in Project F using F4PGA, first ensure that you have installed the Project F
submodule locally. Enter into the ``f4pga-examples`` directory and run:
@ -24,7 +22,7 @@ submodule locally. Enter into the ``f4pga-examples`` directory and run:
.. code-block:: bash
:name: import-projectf
git submodule update --init --recursive
git submodule update --init --recursive
After installing the Submodules, you can run any supported design by calling its makefile:
@ -37,9 +35,9 @@ 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 run ``make download``. For example to download the first design from
hello arty, run the following in F4PGA root directory:
To download the bitstream to the board run ``make download``.
For example, to download the first design from hello arty, run the following in F4PGA's root directory:
.. code-block:: bash

14
xc7/linux_litex_demo/README.rst
View File

@ -1,12 +1,13 @@
Linux LiteX demo
~~~~~~~~~~~~~~~~
This example design features a Linux-capable SoC based around VexRiscv soft
CPU. It also includes DDR and Ethernet controllers. To build the litex example,
run the following commands:
To build the linux-litex-demo example, first re-navigate to the directory that contains examples for Xilinx 7-Series FPGAs. Then depending on your hardware, run:
This example design features a Linux-capable SoC based around VexRiscv soft CPU.
It also includes DDR and Ethernet controllers.
To build the litex example, run the following commands:
To build the linux-litex-demo example, first re-navigate to the directory that contains examples for Xilinx 7-Series
FPGAs.
Then, depending on your hardware, run:
.. code-block:: bash
:name: example-litex-a35t-group
@ -35,8 +36,7 @@ Now you can upload the design with:
The LiteX design is provided with an Ethernet module that uses the ``192.168.100.100/24``
IPv4 address that needs to be set on your network interface.
You may find these information useful to correctly setup the network interface:
https://github.com/timvideos/litex-buildenv/wiki/Networking
You may find these information useful to correctly setup the network interface: :gh:`timvideos/litex-buildenv/wiki/Networking`.
You should observe the following line in the OpenOCD output: