docs/glossary: update

Signed-off-by: Unai Martinez-Corral <[email protected]>

docs/community.rst

@@ -1,3 +1,5 @@
+.. _Community:
+
 Community
 #########
 

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 ➚ <https://IEEE-P1076.gitlab.io/>`__) or
+    emerging software-inspired paradigms like
+    `Chisel ➚ <https://chisel.eecs.berkeley.edu/>`_,
+    `SpinalHDL ➚ <https://spinalhdl.github.io/SpinalDoc-RTD/>`_,
+    `Migen ➚ <https://m-labs.hk/gateware/migen/>`_, or
+    :gh:`Amaranth ➚ <amaranth-lang>`.
+
+  Tool
+    * A software application available as a CLI entrypoint, a shared library or an (interpreted) script.
+
+    * Within :term:`f4pga <F4PGA>`, a *tool* is a Python abstraction that wraps a software application:
+
+    .. image:: _static/images/tool.png
+      :align: center
+
+  Step
+    Within :term:`f4pga <F4PGA>`, a *step* is a unit of execution, which is characterized by a set of
+    :term:`dependencies <Dependency>` and a set of :term:`artifacts <Artifact>`,
+    and it is composable in a :term:`flow <Flow>`.
+    *Steps* might wrap a single or multiple :term:`tools <Tool>`.
+
+    .. image:: _static/images/step.png
+      :align: center
+
+  Flow
+    Within :term:`f4pga <F4PGA>`, a *flow* is a :wikipedia:`directed graph ➚ <Directed_graph>` of :term:`steps <Step>`, 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) ➚ <Command-line_interface>` 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 <F4PGA>` :term:`tools <Tool>` provide Python abstractions around the CLIs.
+
+  Module
+    :ref:`The Python Tutorial » Modules ➚ <python:tut-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 <F4PGA>`, user-defined *modules* allow extending the built-in :term:`flows <Flow>` and
+    :term:`steps <Step>` to achieve custom and/or complex tasks.
+
+  Dependency
+    A *dependency* is a prerequisite to execute a :term:`f4pga <F4PGA>` :term:`step <Step>` in a :term:`flow <Flow>`.
+    *Dependencies* might be files (such as HDL sources, constraints, etc.), :term:`artifacts <Artifact>` from previous
+    *steps* or :term:`tools <Tool>`.
+
+  Artifact
+    An *artifact* is a result produced by a :term:`step <Step>` when executed.
+    Typically, *artifacts* are files and logs generated by the :term:`tools <Tool>`.
+    However, within :term:`f4pga <F4PGA>` :term:`flows <Flow>`, (meta)data can be passed across *steps* without saving
+    it to disk.
+
+  Target
+    Within :term:`f4pga <F4PGA>`, :term:`flows <Flow>` 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 <F4PGA>`, the content of :term:`dependencies <Dependency>` and :term:`artifacts <Artifact>` can
+    be tracked to optimize consecutive executions of the same :term:`flow <Flow>`.
+    The *cache* contains the :wikipedia:`hash ➚ <Hash_function>` of the assets.
+
+  Resolution
+    Relations between :term:`f4pga <F4PGA>` :term:`steps <Step>`, :term:`dependencies <Dependency>` and :term:`artifacts <Artifact>`
+    can get complex easily.
+    On top of computing the topological sorting, :term:`f4pga <F4PGA>` checks the existence of the assets, and supports
+    displaying the status.
+
+  Definition
+    Within :term:`f4pga <F4PGA>`, a :term:`flow <Flow>` *definition* is the description of which :term:`steps <Step>`
+    are to be executed and which :term:`dependencies <Dependency>` and :term:`artifacts <Artifact>` 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 <Design>` or set of
+    designs.
+
+  Design
+    Required :term:`HDL` sources, constraints and other assets to execute a :term:`flow <Flow>` and achieve a task.
+
+  Configuration
+    Within :term:`f4pga <F4PGA>`, a *project configuration* is the set of parameters needed for executing a
+    :term:`flow <Flow>` on a given :term:`design <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 <HDL>` sources interpreted as programming languages by simulators, which can
+      generate interpeted or executable :term:`artifacts <Artifact>`.
+
+  Toolchain
+    :wikipedia:`Toolchain ➚ <Toolchain>` is a generic term used to refer to a set of programming tools used
+    consecutively to perform a complex software development task.