diff --git a/docs/_static/images/flow.png b/docs/_static/images/flow.png new file mode 100644 index 0000000..1f6e7bb Binary files /dev/null and b/docs/_static/images/flow.png differ diff --git a/docs/_static/images/step.png b/docs/_static/images/step.png new file mode 100644 index 0000000..e63a904 Binary files /dev/null and b/docs/_static/images/step.png differ diff --git a/docs/_static/images/tool.png b/docs/_static/images/tool.png new file mode 100644 index 0000000..b6cfc44 Binary files /dev/null and b/docs/_static/images/tool.png differ diff --git a/docs/community.rst b/docs/community.rst index af77034..0b812da 100644 --- a/docs/community.rst +++ b/docs/community.rst @@ -1,3 +1,5 @@ +.. _Community: + Community ######### diff --git a/docs/glossary.rst b/docs/glossary.rst index 62ae531..3eae7fd 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -2,6 +2,129 @@ Glossary ######## .. glossary:: + :sorted: - File - A representation of a physical file. + HDL + A Hardware Description Language (HDL) is a computer language used for describing hardware designs. + HDLs in the scope of F4PGA include established (such as Verilog and `VHDL ➚ `__) or + emerging software-inspired paradigms like + `Chisel ➚ `_, + `SpinalHDL ➚ `_, + `Migen ➚ `_, or + :gh:`Amaranth ➚ `. + + Tool + * A software application available as a CLI entrypoint, a shared library or an (interpreted) script. + + * Within :term:`f4pga `, a *tool* is a Python abstraction that wraps a software application: + + .. image:: _static/images/tool.png + :align: center + + Step + Within :term:`f4pga `, a *step* is a unit of execution, which is characterized by a set of + :term:`dependencies ` and a set of :term:`artifacts `, + and it is composable in a :term:`flow `. + *Steps* might wrap a single or multiple :term:`tools `. + + .. image:: _static/images/step.png + :align: center + + Flow + Within :term:`f4pga `, a *flow* is a :wikipedia:`directed graph ➚ ` of :term:`steps `, which + describes end-to-end sequences to achieve specific tasks. + A *flow* might used as a step within another *flow*. + In such cases, terms *subflow* or *partial flow* are used. + + .. image:: _static/images/flow.png + :align: center + + CLI + A :wikipedia:`Command-Line Interface (CLI) ➚ ` is an application that processes commands to + a computer program in the form of lines of text, typically interactively (through a terminal) or in batch mode + (through scripts). + Most of the applications used in F4PGA are meant to be used through CLIs. + Precisely, :term:`f4pga ` :term:`tools ` provide Python abstractions around the CLIs. + + Module + :ref:`The Python Tutorial » Modules ➚ ` are files containing Python statements and definitions + (variables, functions, clases,...). + The file name is the module name with the suffix ``.py`` appended. + + Within :term:`f4pga `, user-defined *modules* allow extending the built-in :term:`flows ` and + :term:`steps ` to achieve custom and/or complex tasks. + + Dependency + A *dependency* is a prerequisite to execute a :term:`f4pga ` :term:`step ` in a :term:`flow `. + *Dependencies* might be files (such as HDL sources, constraints, etc.), :term:`artifacts ` from previous + *steps* or :term:`tools `. + + Artifact + An *artifact* is a result produced by a :term:`step ` when executed. + Typically, *artifacts* are files and logs generated by the :term:`tools `. + However, within :term:`f4pga ` :term:`flows `, (meta)data can be passed across *steps* without saving + it to disk. + + Target + Within :term:`f4pga `, :term:`flows ` can have multiple leaf *steps*, producing different results off some + shared previous *steps*. + The *target* of a *flow* specifies which *steps* to execute in a run. + + F4PGA + + * *Uppercase*: + + * FOSS Flows For FPGA (F4PGA), the name of the project as a whole. + + * A Workgroup under the CHIPS Alliance. + See :ref:`Community`. + + * *Lowercase*: + + * Python package providing utilities. + + * The main CLI entrypoint provided by the Python package. + + Cache + Within :term:`f4pga `, the content of :term:`dependencies ` and :term:`artifacts ` can + be tracked to optimize consecutive executions of the same :term:`flow `. + The *cache* contains the :wikipedia:`hash ➚ ` of the assets. + + Resolution + Relations between :term:`f4pga ` :term:`steps `, :term:`dependencies ` and :term:`artifacts ` + can get complex easily. + On top of computing the topological sorting, :term:`f4pga ` checks the existence of the assets, and supports + displaying the status. + + Definition + Within :term:`f4pga `, a :term:`flow ` *definition* is the description of which :term:`steps ` + are to be executed and which :term:`dependencies ` and :term:`artifacts ` are to be passed + along. + + Constraints + Set of parameters that allow users to select/specify certain physical characteristics of the FPGA device, such as + the pins/pads or the logic standard to use. + + Project + A set of :term:`HDL` sources, constraints and other assets used in a hardware :term:`design ` or set of + designs. + + Design + Required :term:`HDL` sources, constraints and other assets to execute a :term:`flow ` and achieve a task. + + Configuration + Within :term:`f4pga `, a *project configuration* is the set of parameters needed for executing a + :term:`flow ` on a given :term:`design `. + The *configuration* might be provided through a Python API, or through a file using declarative format (such as JSON, + YAML, INI,...). + + Model + * *Project model*: a generic description of an EDA project, independent of vendor and tools. + It reflects multiple design variants, grouping of source files into file sets or linking testbenches to + components or subsystems in a design. + * *Simulation model*: :term:`HDL ` sources interpreted as programming languages by simulators, which can + generate interpeted or executable :term:`artifacts `. + + Toolchain + :wikipedia:`Toolchain ➚ ` is a generic term used to refer to a set of programming tools used + consecutively to perform a complex software development task.