diff --git a/docs/customizing-makefiles.rst b/docs/customizing-makefiles.rst index 5edeb4e..46af68f 100644 --- a/docs/customizing-makefiles.rst +++ b/docs/customizing-makefiles.rst @@ -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 `_ 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 := SOURCES := ${current_dir}/ - - # 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}/ PCF := ${current_dir}/ @@ -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` 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` 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` 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 +: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 @@ -58,35 +58,35 @@ design using the following syntax: ${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 +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 ` show how you can specify what constraint files are being used for +: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:: .. group-tab:: XDC - + .. code-block:: bash XDC := ${current_dir}/ @@ -99,19 +99,19 @@ your design. The general syntax depends on whether you are using XDC files or a SDC := ${current_dir}/ -.. note:: +.. note:: :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. + path for the current directory. :ref:`Line 9 ` 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 `_: +(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 `: .. code-block:: bash @@ -133,13 +133,13 @@ is from lines 9-39 of `the Makefile from counter test `` diff --git a/docs/index.rst b/docs/index.rst index b55f80e..6ec20de 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 `_ -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 ` +GitHub repository. +It currently focuses on the following FPGA families: - Artix-7 from Xilinx, - EOS S3 from QuickLogic. diff --git a/docs/project-f.rst b/docs/project-f.rst index 43f49b7..b0eef37 100644 --- a/docs/project-f.rst +++ b/docs/project-f.rst @@ -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 `_ are currently - officially supported. To track the progress of the MMCME2_BASE see issue - `#153 `_ in f4pga examples and - issue `#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 `_ 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 ` are + currently officially supported. + To track the progress of the MMCME2_BASE see :ghissue:`153` and issue :gh:`chipsalliance/f4pga-arch-defs#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 `_. +the designs and how they work on `the developers blog `_. 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 diff --git a/xc7/linux_litex_demo/README.rst b/xc7/linux_litex_demo/README.rst index 91127e8..ad77329 100644 --- a/xc7/linux_litex_demo/README.rst +++ b/xc7/linux_litex_demo/README.rst @@ -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: