Hardware
/
f4pga
mirror of https://github.com/chipsalliance/f4pga.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Spelling corrections 

Signed-off-by: Krzysztof Boronski <kboronski@antmicro.com>
This commit is contained in:
Krzysztof Boronski 2022-05-11 08:14:50 -05:00
parent 3f5202d2ba
commit 080a59884a
8 changed files with 85 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/f4pga/DevNotes.md
View File

@ -11,17 +11,17 @@ For more detailed, up-to-date information about the code, refer to the pydoc doc
## Project's structure
* `__init__.py` contains the logic and entrypoint of the build system
* `__init__.py` contains the logic and entry point of the build system
* `argparser.py` contains boring code for CLI interface
* `cache.py` contains code needed for tracking modifications in the project.
* `common.py` contains code shared by the main utility and the modules
* `flow_config.py` contains code for reading and accessing flow definitions and configurations
* `module_inspector.py` contains utilities for inpecting I/O of modules
* `module_runner.py` contains code required to load modules at runtime
* `module_inspector.py` contains utilities for inspecting I/O of modules
* `module_runner.py` contains code required to load modules at run-time
* `module.py` contains definitions required for writing and using f4pga modules
* `part_db.json` contains mappings from part names to platform names
* `setup.py` contains a package installation script
* `stage.py` contains classes relevant to stage represetation
* `stage.py` contains classes relevant to stage representation
* `modules` contains loadable modules
* `platforms` contains platform flow definitions
@ -51,7 +51,7 @@ _DFS_ approach to invoke modules and check their inputs and outputs.
### Modification tracking
Modification tracking is done by taking, comparing and keeping track of `adler32`
hashes of all dependencies. Each dependency has a set of hashes associted with it.
hashes of all dependencies. Each dependency has a set of hashes associated with it.
The reason for having multiple hashes is that a dependency may have multiple
"_consumers_", ie. _stages_ which take it as input. Each hash is associated with
particular consumer. This is necessary, because the system tries to avoid rebuilds
@ -67,9 +67,9 @@ _f4pga_ exposes some data to the user as well as reads some using internal
environmental variables. These can be referenced by users in
_platform flow definitions_ and _project flow configurations_ using the
`${variable_name}` syntax when defining values. They can also be read inside
_f4pga modules_ by accesing the `ctx.values` namespace.
_f4pga modules_ by accessing the `ctx.values` namespace.
The core of tis system is the `ResolutionEnvironemt` class which can be found
The core of its system is the `ResolutionEnvironemt` class which can be found
inside the `common` module.
### Installation
@ -84,18 +84,18 @@ Check `CMakeLists.txt`.
* Force "_on-demand_" outputs if they are required by another stage.
This may require redesigning the "on-demand" feature, which currently works
by producing a dependency if and only if the user explicitely provides the
by producing a dependency if and only if the user explicitly provides the
path. Otherwise the path is unknown.
* Make commenting style consistent
* Document writing flow defintions
* Document writing flow definitions
* Extend the metadata system for modules, perhaps make it easier to use.
* Add missing metadata for module targets.
* (_suggestion_) Generate platform defintions using CMake.
* (_suggestion_) Generate platform definitions using CMake.
### Out of the current scope

88
docs/f4pga/Usage.md
View File

@ -31,7 +31,7 @@ If you want to create a new project, it's highly recommended that you read this
### f4pga
`f4pga` is a modular build system designed to handle various _Verilog-to-bitsream_ flows for FPGAs.
`f4pga` is a modular build system designed to handle various _Verilog-to-bitstream_ flows for FPGAs.
It works by wrapping the necessary tools in Python, which are called *f4pga modules*.
Modules are then referenced in *platform flow definition* files, together with configuration specific for a given
platform.
@ -55,7 +55,7 @@ _modules_ and f4pga _modules_) is a Python script that wraps a tool used within
The main purpose of the wrappers is to provide a unified interface for `f4pga` to use and to configure the tool,
as well as provide information about files required and produced by the tool.
### Dependecies
### Dependencies
A *dependency* is any file, directory or a list of such that a *module* takes as its input or produces on its output.
@ -83,10 +83,10 @@ a stage, there's a `--nocache` option that treats the `.symbicache` file as if i
### Resolution
A *dependency* is said to be *resolved* if it meets one of the following critereia:
A *dependency* is said to be *resolved* if it meets one of the following criteria:
* it exists on persistent storage and its hash matches the one stored in .symbicache
* there exists such *flow* that all of the dependieces of its modules are *resolved* and it produces the *dependency* in
* there exists such *flow* that all of the dependencies of its modules are *resolved* and it produces the *dependency* in
question.
### Platform's flow definition
@ -99,12 +99,12 @@ the modules can reference.
In case of some modules it may also define a set of parameters used during their construction.
`mkdirs` module uses that to allow production of of multiple directories as separate dependencies.
This however is an experimental feature which possibly will be removed in favor of having multiple instances of the same
module with renameable ouputs.
module with renameable outputs.
Not all *dependencies** have to be *resolved* at this stage, a *platform's flow definition* for example won't be able to
provide a list of source files needed in a *flow*.
### Projects's flow configuration
### Project's flow configuration
Similarly to *platform flow definition*, *Projects flow configuration* is a _JSON_ that is used to configure *modules*. There are however a couple differences here and there.
@ -157,10 +157,10 @@ For example, let's consider the following *projects flow configuration (flow.jso
```
It specifies list of paths to Verilog source files as `sources` dependency.
Similarily it also provides an `XDC` file with constrains (`xdc` dependency).
Similarly it also provides an `XDC` file with constrains (`xdc` dependency).
It also names a path for synthesis and logs (`synth_log`, `pack_log`).
These two are optional on-demand outputs, meaning they won't be produces unless their paths are explicitely set.
These two are optional on-demand outputs, meaning they won't be produces unless their paths are explicitly set.
`top` value is set to in order to specify the name of top Verilog module, which is required during synthesis.
@ -208,20 +208,20 @@ as strings unless the follow one of the following format:
* `[item1,item2,item3,...]` - this is a list of strings
* `{key1:value1,key2:value2,key3:value3,...}` - this is a dictionary
Nesting structures is curently unsupported in CLI.
Nesting structures is currently unsupported in CLI.
### Pretend mode
You can also add a `--pretend` (`-P`) option if you just want to see the results of dependency resolution for a
specified target without building it.
This is useful when you just want to know what files will be generated and where wilh they be stored.
This is useful when you just want to know what files will be generated and where will they be stored.
### Info mode
Modules have the ability to include description to the dependencies they produce.
Running `f4pga` with `--info` (`-i`) flag allows youn to see descriptions of these dependencies.
This option doesn't require a target to be specified, but you still have to provuide a flow configuration and platform
Running `f4pga` with `--info` (`-i`) flag allows you to see descriptions of these dependencies.
This option doesn't require a target to be specified, but you still have to provide a flow configuration and platform
name.
This is still an experimental option, most targets currently lack descriptions and no information whether the output is
@ -258,23 +258,23 @@ This is only a snippet of the entire output.
| long | short | arguments | description |
|-----------|:-----:|--------------------------|----------------------------------------------------------------------------|
| --verobse | -v | - | Constrol verbosity level. 0 for no verbose output. 2 for maximum verbisity |
| --silent | -s | - | Surpress any output |
| --verbose | -v | - | Control verbosity level. 0 for no verbose output. 2 for maximum verbosity |
| --silent | -s | - | Suppress any output |
### Summary of all available subcommands
### Summary of all available sub-commands
| name | description |
|---------|-----------------------------|
| build | Build a project |
| showd | Print value of a dependency
### Summary of all options available for `build` subcommand
### Summary of all options available for `build` sub-command
| long | short | arguments | description |
|-------------|:-----:|--------------------------|---------------------------------------------------------|
| --flow | -f | flow configuration file | Use flow configuration file |
| --platform | | platform name | Specify target platform name (eg. x7a100t) |
| --part | -p | part name | Speify target platform by part name |
| --part | -p | part name | Specify target platform by part name |
| --target | -t | target dependency name | Specify target to produce |
| --info | -i | - | Display information about available targets |
| --pretend | -P | - | Resolve dependencies without executing the flow |
@ -283,7 +283,7 @@ This is only a snippet of the entire output.
| --dep | -D | dependency_name=pathexpr | Add a dependency to configuration |
| --val | -V | value_name=valueexpr | Add a value to configuration |
### Summary of all options available for `showd` subcommand
### Summary of all options available for `showd` sub-command
| long | short | arguments | description |
|-------------|:-----:|--------------------------|--------------------------------------------------------------------------|
@ -320,7 +320,7 @@ Project status:
f4pga: DONE
```
The letters in the boxes describe the status of a dependency which's name is next to the box.
The letters in the boxes describe the status of a dependency whose name is next to the box.
* **X** - dependency unresolved.
Dependency is not present or cannot be produced.
@ -339,11 +339,11 @@ The letters in the boxes describe the status of a dependency which's name is nex
This should be fixed in the future.
:::
* **S** - depenendency not present, resolved.
* **S** - dependency not present, resolved.
This dependency is not currently available on the persistent storage, however it will be produced within flow's
execution.
* **R** - depenendency present, resolved, requires rebuild.
* **R** - dependency present, resolved, requires rebuild.
This dependency is currently available on the persistent storage, however it has to be rebuilt due to the changes in
the project.
@ -356,11 +356,11 @@ Additional info about a dependency will be displayed next to its name after a co
* In case of dependencies which do not require execution of any modules, only a path or list of paths to
file(s)/directory(ies) that will be displayed.
* In case of unresolved dependencies (**X**), which are never produced by any module, a text sying "`MISSING`" will be
* In case of unresolved dependencies (**X**), which are never produced by any module, a text saying "`MISSING`" will be
displayed.
In the example above file `counter.v` has been modified and is now marked as "**N**".
This causes a bunch of other dependencies to be reqbuilt ("**R**").
This causes a bunch of other dependencies to be rebuilt ("**R**").
`build_dir` and `xdc` were already present, so they are marked as "**O**".
## Common targets and values
@ -379,31 +379,31 @@ Below are lists of the target and value names along with their meanings.
### Available in most flows
| Target name | list | Description |
|-------------|:----:|-------------|
| `eblif` | no | Extended blif file |
| `bitstream` | no | Bitstream |
| `net` | no | Netlist |
| `fasm` | no | Final FPGA Assembly |
| `fasm_extra` | no | Additional FPGA assembly that may be generated during synthesis |
| `build_dir` | no | A directory to put the output files in |
| Target name | list | Description |
|--------------|:----:|-----------------------------------------------------------------|
| `eblif` | no | Extended blif file |
| `bitstream` | no | Bitstream |
| `net` | no | Netlist |
| `fasm` | no | Final FPGA Assembly |
| `fasm_extra` | no | Additional FPGA assembly that may be generated during synthesis |
| `build_dir` | no | A directory to put the output files in |
### Built-in values
| Value name | type | Description |
|------------|------|-------------|
| `shareDir` | `string` | Path to f4pga's installation "share" directory |
| `python3` | `string` | Path to Python 3 executable |
| Value name | type | Description |
|-----------------|----------|---------------------------------------------------|
| `shareDir` | `string` | Path to f4pga's installation "share" directory |
| `python3` | `string` | Path to Python 3 executable |
| `noisyWarnings` | `string` | Path to noisy warnings log (should be deprecated) |
| `prjxray_db` | `string` | Path to Project X-Ray database |
| `prjxray_db` | `string` | Path to Project X-Ray database |
### Used in flow definitions
| Value name | type | Description |
|------------|------|-------------|
| `top` | `string` | Top module name |
| `build_dir` | `string` | Path to build directory (should be optional) |
| `device` | `string` | Name of the device |
| `vpr_options` | `dict[string -> string \| number]` | Named ptions passed to VPR. No `--` prefix included. |
| `part_name` | `string` | Name of the chip used. The distinction between `device` and `part_name` is ambiguous at the moment and should be addressed in the future. |
| `arch_def` | `string` | Path to an XML file containing architecture definition. |
| Value name | type | Description |
|---------------|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `top` | `string` | Top module name |
| `build_dir` | `string` | Path to build directory (should be optional) |
| `device` | `string` | Name of the device |
| `vpr_options` | `dict[string -> string \| number]` | Named options passed to VPR. No `--` prefix included. |
| `part_name` | `string` | Name of the chip used. The distinction between `device` and `part_name` is ambiguous at the moment and should be addressed in the future. |
| `arch_def` | `string` | Path to an XML file containing architecture definition. |

4
docs/f4pga/modules/fasm.md
View File

@ -1,6 +1,6 @@
# fasm
The _fasm_ module generates FPGA assebly using `genfasm` (VPR-only).
The _fasm_ module generates FPGA assembly using `genfasm` (VPR-only).
The module should guarantee the following outputs:
* `fasm`
@ -14,5 +14,5 @@ The setup of the synth module follows the following specifications:
The `fasm` module accepts the following values:
* `pnr_corner` (string, optional): PnR conrenr to use. Relevant only for Quicklogic's
* `pnr_corner` (string, optional): PnR corner to use. Relevant only for Quicklogic's
eFPGAs.

4
docs/f4pga/modules/generic_script_wrapper.md
View File

@ -19,8 +19,8 @@ Parameters are everything when it comes to this module:
* `file` (string, required if `mode` is "file"): Name of the file generated by the
script.
* `target` (string, required): Default name of the file of the generated
dependency. You can use all values available durng map_io stage. Each input
dependency alsogets two extra values associated with it:
dependency. You can use all values available during map_io stage. Each input
dependency also gets two extra values associated with it:
`:dependency_name[noext]`, which contains the path to the dependency the
extension with anything after last "." removed and `:dependency_name[dir]` which
contains directory paths of the dependency. This is useful for deriving an output

36
docs/f4pga/modules/index.md
View File

@ -8,7 +8,7 @@ modules.
### Configuration interface:
Modules are configured through an internal API by _**sfbuf4pgaild**_.
Modules are configured through an internal API by _**f4pga**_.
The basic requirement for a module script is to expose a class with `Module`
interface.
@ -17,7 +17,7 @@ _**f4pga**_ reads its configuration from two different sources:
and **project's flow configuration**, which is a set of configuration options provided by the user
through a JSON file or CLI interface.
Thosse sources contain snippets of _module configurations_.
Those sources contain snippets of _module configurations_.
A _module configuration_ is a structure with the following fields:
@ -37,12 +37,12 @@ A _module configuration_ is a structure with the following fields:
In case of **platform's flow definition**, a `values` dictionary can be defined
globally and the values defined there will be passed to every module's config.
Those values can be overriden per-module through `module_options` dictionary.
Those values can be overridden per-module through `module_options` dictionary.
Parameters used during module's construction can also be defined in `module_options`
as `params` (those are not a part of _module configuration_, instead they are used
during the actual construction of a module instance, before it declares any of its
input/outputs etc.. This is typically used to acieve some parametrization over module's
input/outputs etc.. This is typically used to achieve some parametrization over module's
I/O).
Defining dictionaries for `takes` and `produces` is currently disallowed within
@ -65,12 +65,12 @@ Unlike **platform's flow definition**, **project's flow configuration** may cont
names to actual paths. Most dependencies can have their paths resolved implicitly
without the need to provide explicit paths, which is a mechanism that is described
in a later section of this document. However some dependencies must be provided
explicitelly, eg. paths to project's verilog source files. It should be noted that
explicitly, eg. paths to project's Verilog source files. It should be noted that
depending on the flow definition and the dependency in question, the path does not
necessarily have to point to an already existing file. If the dependency is a
product of a module within the flow, the path assigned to it will be used
by the module to build that dependency. This is also used to in case of _on-demand_
dependencies, which won't be produced unless the user explicitelly provides a path
dependencies, which won't be produced unless the user explicitly provides a path
for them.
**project's flow configuration** cannot specify `params` for modules and does not
@ -85,11 +85,11 @@ overload the `dependecies` and `values` defined in a global scope of
is treated as a _stage-specific-configuration_. The key is a name of a stage within
a flow for the specified platform and the values are dicts which may contain
`dependencies` and `values` fields that overload `dependencies` and `values`
repespectively, locally for the stage. Additionally a `default_target` field can be
provided to specify a default target to built when the user does not specify it throgh
a CLI inteface.
respectively, locally for the stage. Additionally a `default_target` field can be
provided to specify a default target to built when the user does not specify it through
a CLI interface.
The afromentioned _*exceptions_ are:
The aforementioned _*exceptions_ are:
* `dependencies` - dependencies shared by all platforms.
* `values` - values shared by all platforms
@ -145,7 +145,7 @@ With the following values defined
```
Be careful when using this kind of resolution, as it's computational and memory
complexity grows exponentially in ragards to the number of list variables being
complexity grows exponentially in regards to the number of list variables being
referenced, which is a rather obvious fact, but it's still worth mentioning.
The variables that can be referenced within a definition/configuration fall into 3
@ -171,7 +171,7 @@ categories:
### `Module` class
Each nmodule is represented as a class derived from `Module` class.
Each module is represented as a class derived from `Module` class.
The class should implement the following methods:
@ -187,7 +187,7 @@ when instantiating a module.
### Module's execution modes
A module ahas essentially two execution modes:
A module has essentially two execution modes:
* _mapping_ mode
* _exec_ mode
@ -196,7 +196,7 @@ A module ahas essentially two execution modes:
In _mapping_ mode the module is provided with an incomplete configuration which
includes:
* `takes` namespace: this maps names of input dependecies to the paths of these
* `takes` namespace: this maps names of input dependencies to the paths of these
dependencies
* `values` namespace: this maps names of variables to the values of those
variables.
@ -218,7 +218,7 @@ In _exec_ mode the module does the actual work.
The configuration passed into this mode is full and it includes:
* `takes` namespace: this maps names of input dependecies to the paths of these
* `takes` namespace: this maps names of input dependencies to the paths of these
dependencies
* `values` namespace: this maps names of variables to the values of those
variables.
@ -235,7 +235,7 @@ described in `outputs` should be present.
In the the `__init__` method of module's class, the following fields should be
set:
* `takes` - a list of symbolic dependency names for dependencies used byb the module
* `takes` - a list of symbolic dependency names for dependencies used by the module
* `produces` - a list of symbolic dependencies names for dependencies produced
by the module.
* `values` - a list of names given to the variables used withing the module
@ -251,9 +251,9 @@ ways:
* '`?`' _suffix_
* In `takes` - the dependency is not necessary for the module to execute
* In `produces` - the dependency may be produceed, but it is not guaranteed.
* In `produces` - the dependency may be produced, but it is not guaranteed.
* In `values` the value is not required for the module to execute.
Refferreing to it through `ModuleContext.values.value_name` won't raise an
Referring to it through `ModuleContext.values.value_name` won't raise an
exception if the value is not present, instead `None` will be returned.
* '`!`' _suffix_
* In `produces` - the dependency is going to be produced only if the user

4
docs/f4pga/modules/io_rename.md
View File

@ -1,7 +1,7 @@
# io_rename
This module provides a way to rename (ie. change) dependencies and values of an
instance of a different module. It wraps another, module whoose name is specified in `params.module` and changes the names of the dependencies and values it relies on.
instance of a different module. It wraps another, module whose name is specified in `params.module` and changes the names of the dependencies and values it relies on.
## Parameters
@ -18,7 +18,7 @@ Not specifying a mapping for a given entry will leave it with its original name.
## Values
All values specified for this modules will be accessible by tyhe wrapped module.
All values specified for this modules will be accessible by the wrapped module.
## Extra notes

4
docs/f4pga/modules/mkdirs.md
View File

@ -1,9 +1,9 @@
# mkdirs
This modules creates directiories specified by the author of flow definition
This modules creates directories specified by the author of flow definition
as its targets..
## Parameters
Each key serves as aname of a directory to becreated, while the value is the
Each key serves as a name of a directory to be created, while the value is the
path for that directory.

10
docs/f4pga/modules/synth.md
View File

@ -12,9 +12,9 @@ The module should guarantee the following outputs:
For detailed information about these targets, please refer to
`docs/common targets and variables.md`
What files and how are they generated is dependendent on TCL scripts executed
What files and how are they generated is dependent on TCL scripts executed
withing YOSYS and the script vary depending on the target platform. Due to this
design choice it is required for the author of the flow defnition to parametrize
design choice it is required for the author of the flow definition to parameterize
the `synth` module in a way that will **GUARANTEE** the targets mentioned above
will be generated upon a successful YOSYS run.
@ -31,11 +31,11 @@ The list should specify additional targets that will be generated
The `synth` module requires the following values:
* `tcl_scripts` (string, required): A path to a directory containing `synth.tcl`
and `conv.tcl` scripts that wiull be used by YOSYS.
* `read_verilog_args` (list[string | number], optional) - If specified, the verilog
and `conv.tcl` scripts that will be used by YOSYS.
* `read_verilog_args` (list[string | number], optional) - If specified, the Verilog
sources will be read using the `read_verilog` procedure with options contained in
this value.
* `yosys_tcl_env` (dict[string -> string | list[string], required) - A mapping that
defines environmental variables that will be used within the TCL scripts. This
should contain the references to module's inputs and outputs in order to gurantee
should contain the references to module's inputs and outputs in order to guarantee
the generation of the desired targets.