From 0103506a38d2d50ff4b95c89d3c96aec597670a5 Mon Sep 17 00:00:00 2001 From: "Rodrigo A. Melo" Date: Sun, 11 Aug 2024 22:10:01 -0300 Subject: [PATCH] docs: rewritten basic usage --- docs/basic.rst | 163 ++++++++++++++++++++++--------------------------- docs/index.rst | 5 -- 2 files changed, 74 insertions(+), 94 deletions(-) diff --git a/docs/basic.rst b/docs/basic.rst index b178c0fc..5efcfccd 100644 --- a/docs/basic.rst +++ b/docs/basic.rst @@ -1,148 +1,133 @@ Basic usage =========== -.. ATTENTION:: +Project Configuration +--------------------- - (2024-08-08) To be updated. +The first steps involve importing the necessary module to support the desired tool and instantiating the corresponding *class*: -Project Creation ----------------- +.. code-block:: python + + from pyfpga.vivado import Vivado + + prj = Vivado('PRJNAME', odir='OUTDIR') -The first steps are import the module and instantiate the ``Project`` *class*, -specifying the *TOOL* to use and, optionally, a *PROJECT NAME* (the *tool* -name is used when *no name* is provided). +In the example, we are using Vivado, specifying the optional parameter *project name* (*tool name* if omitted) and *output directory* (*results* by default). + +Next step is to specify the target FPGA device: .. code-block:: python - from fpga.project import Project + prj.set_part('xc7k160t-3-fbg484') + +.. note:: - prj = Project('vivado', 'projectName') + Default parts are provided for each supported tool. -By default, the directory where the project is generated is called ``build`` -and is located in the same place that the script, but another name and location -can be specified. +HDL source files are added using one of the following methods: .. code-block:: python - prj.set_outdir('../temp') + prj.add_vhdl('PATH_TO_FILES_GLOB_COMPATIBLE', 'OPTIONAL_LIBNAME') + prj.add_vlog('PATH_TO_FILES_GLOB_COMPATIBLE') + prj.add_slog('PATH_TO_FILES_GLOB_COMPATIBLE') -Next, the FPGA part would be specified: +In these methods, you provide a path to the files. The path can include wildcards (like `*.vhdl`), allowing you to match multiple files at once. -.. code-block:: python +For `add_vhdl`, you can also optionally specify a library name where the files will be included. - prj.set_part('xc7k160t-3-fbg484') +.. note:: + + Internally, the methods that specify files use `glob`_ to support wildcards and `Path`_ to obtain absolute paths. -.. NOTE:: + .. _glob: https://docs.python.org/3/library/glob.html + .. _Path: https://docs.python.org/3/library/pathlib.html - You can use the default FPGA part for a quick test or make a lazy comparison - between tools, but generally, you will want to specify a particular one. - Examples about how to specify a part according the tool, are (default values - when ``set_part`` is not employed): +Generics/parameters can be specified with: + +.. code-block:: python - * **Ise:** ``xc7k160t-3-fbg484`` (*device-speed-package*) - * **Libero:** ``mpf100t-1-fcg484`` (*device-speed-package*) - * **Openflow:** ``hx8k-ct256`` (*device-package*) - * **Quartus:** ``10cl120zf780i8g`` (*part*) - * **Vivado:** ``xc7k160t-3-fbg484`` (*part*) + prj.add_param('PARAMNAME', 'PARAMVALUE') -The files addition method allows specifying one or more HDL or constraint files -(also block designs in case of Vivado). -It uses ``glob`` internally, which makes available the use of wildcards. -The path to their location must be relative to the Python script, and there -are optional parameters to indicate the file type (``vhdl``, ``verilog``, -``constraint`` or ``design``), which is automatically detected based on the -file extension, and if it is a member of a VHDL package. +For Verilog and SystemVerilog, the following methods are also available: .. code-block:: python - prj.add_files('hdl/blinking.vhdl', library='examples') - prj.add_files('hdl/examples_pkg.vhdl', library='examples') - prj.add_files('hdl/top.vhdl') + prj.add_include('PATH_TO_A_DIRECTORY') + prj.add_define('DEFNAME', 'DEFVALUE') -.. NOTE:: +Constraint source files are included using the following: - * In some cases, the files order could be a problem, so take into account to - change the order if needed. - * If a file seems unsupported, you can always use the ``prefile`` or - ``project`` :ref:`hooks`. - * In case of Verilog, ``add_vlog_include`` can be used to specify where to - search for included files. +.. code-block:: python + + prj.add_cons('PATH_TO_FILES_GLOB_COMPATIBLE') -Finally, the top-level must be specified: +Finally, the top-level can be specified as follows: .. code-block:: python prj.set_top('Top') -.. NOTE:: +.. note:: - A relative path to a valid VHDL/Verilog file is also accepted by ``set_top``, - to automatically extract the top-level name. + The order of the methods described in this section is not significant. + They will be arranged in the required order by the underlying template. -Project generation ------------------- +Bitstream generation +-------------------- -Next step if to generate the project. In the most basic form, you can run the -following to get a bitstream: +After configuring the project, you can run the following to generate a bitstream: .. code-block:: python - prj.generate() + prj.make() -Additionally, you can specify which task to perform: +By default, this method performs *project creation*, *synthesis*, *place and route*, and *bitstream generation*. +However, you can optionally specify both the initial and final stages, as follows: .. code-block:: python - prj.generate('syn') - -.. NOTE:: - - The valid values are: + prj.make(first='syn', last='par') - * ``prj``: to generate only a project file (only supported for privative tools) - * ``syn``: to performs synthesis. - * ``imp``: to performs synthesis and implementation (place and route, - optimizations and static timming analysis when available). - * ``bit``: (default) to perform synthesis, implementation and bitstream generation. +.. note:: -Bitstream transfer ------------------- + Valid values are: -This method is in charge of run the needed tool to transfer a bitstream to a -device (commonly an FPGA, but memories are also supported in some cases). -It has up to four main optional parameters: + * ``cfg``: generates the project file + * ``syn``: performs synthesis + * ``par``: performs place and route + * ``bit``: performs bitstream generation -.. code-block:: python +.. note:: - prj.transfer(devtype, position, part, width) + After executing this method, you will find the file `.tcl` (or `sh` in some cases) in the output directory. + For debugging purposes, if things do not work as expected, you can review this file. -Where *devtype* is ``fpga`` by default but can also be ``spi``, ``bpi``, etc, if -supported. An integer number can be used to specify the *position* (1) in the -Jtag chain. When a memory is used as *devtype*, the *part* name and the -*width* in bits must be also specified. +Bitstream programming +--------------------- -.. NOTE:: +The final step is programming the FPGA: - * In Xilinx, `spi` and `bpi` memories are out of the Jtag chain and are - programmed through the FPGA. You must specify the FPGA *position*. - * In a Linux systems, you need to have permission over the device - (udev rule, be a part of a group, etc). +.. code-block:: python -Logging capabilities --------------------- + prj.prog('BITSTREAM', 'POSITION') -PyFPGA uses the `logging `_ -module, with a *NULL* handler and the *INFO* level by default. -Messages can be enabled with: +Both `BITSTREAM` and `POSITION` are optional. +If `BITSTREAM` is not specified, PyFPGA will attempt to discover it based on project information. +The `POSITION` parameter is not always required (depends on the tool being used). -.. code-block:: python +.. note:: - import logging + After executing this method, you will find the file `prog.tcl` (or `sh` in some cases) in the output directory. + For debugging purposes, if things do not work as expected, you can review this file. - logging.basicConfig() +Debugging +--------- -You can enable *DEBUG* messages adding: +Under the hood, `logging`_ is employed. To enable debug messages, you can use: .. code-block:: python - logging.getLogger('fpga.project').level = logging.DEBUG + prj.set_debug() + +.. _logging: https://docs.python.org/3/library/logging.html diff --git a/docs/index.rst b/docs/index.rst index e9241b3e..3e8dfcb0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,11 +6,6 @@ PyFPGA's documentation :align: center :target: https://github.com/PyFPGA/pyfpga -.. ATTENTION:: - - (2024-05-31) PyFPGA is in the process of being strongly rewritten/simplified. - Most changes are internal, but the API will also change. - .. toctree:: intro