docs/glossary: update

Signed-off-by: Unai Martinez-Corral <umartinezcorral@antmicro.com>
This commit is contained in:
Unai Martinez-Corral 2022-03-16 04:15:29 +01:00
parent b200a0e6cd
commit c978d0276b
5 changed files with 127 additions and 2 deletions

BIN
docs/_static/images/flow.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 10 KiB

BIN
docs/_static/images/step.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 11 KiB

BIN
docs/_static/images/tool.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.4 KiB

View File

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

View File

@ -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.