From 080a59884a441f39c8be83dd67e5dae496661296 Mon Sep 17 00:00:00 2001 From: Krzysztof Boronski Date: Wed, 11 May 2022 08:14:50 -0500 Subject: [PATCH] Spelling corrections Signed-off-by: Krzysztof Boronski --- docs/f4pga/DevNotes.md | 20 ++--- docs/f4pga/Usage.md | 88 ++++++++++---------- docs/f4pga/modules/fasm.md | 4 +- docs/f4pga/modules/generic_script_wrapper.md | 4 +- docs/f4pga/modules/index.md | 36 ++++---- docs/f4pga/modules/io_rename.md | 4 +- docs/f4pga/modules/mkdirs.md | 4 +- docs/f4pga/modules/synth.md | 10 +-- 8 files changed, 85 insertions(+), 85 deletions(-) diff --git a/docs/f4pga/DevNotes.md b/docs/f4pga/DevNotes.md index fabce08..de2ea74 100644 --- a/docs/f4pga/DevNotes.md +++ b/docs/f4pga/DevNotes.md @@ -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 diff --git a/docs/f4pga/Usage.md b/docs/f4pga/Usage.md index cb877f8..163145f 100644 --- a/docs/f4pga/Usage.md +++ b/docs/f4pga/Usage.md @@ -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. | diff --git a/docs/f4pga/modules/fasm.md b/docs/f4pga/modules/fasm.md index 94cdcd3..2395c63 100644 --- a/docs/f4pga/modules/fasm.md +++ b/docs/f4pga/modules/fasm.md @@ -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. \ No newline at end of file diff --git a/docs/f4pga/modules/generic_script_wrapper.md b/docs/f4pga/modules/generic_script_wrapper.md index 207a2df..77aa0f2 100644 --- a/docs/f4pga/modules/generic_script_wrapper.md +++ b/docs/f4pga/modules/generic_script_wrapper.md @@ -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 diff --git a/docs/f4pga/modules/index.md b/docs/f4pga/modules/index.md index 262a76f..7083e9a 100644 --- a/docs/f4pga/modules/index.md +++ b/docs/f4pga/modules/index.md @@ -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 diff --git a/docs/f4pga/modules/io_rename.md b/docs/f4pga/modules/io_rename.md index e84730a..ee59125 100644 --- a/docs/f4pga/modules/io_rename.md +++ b/docs/f4pga/modules/io_rename.md @@ -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 diff --git a/docs/f4pga/modules/mkdirs.md b/docs/f4pga/modules/mkdirs.md index bcdafba..01e491e 100644 --- a/docs/f4pga/modules/mkdirs.md +++ b/docs/f4pga/modules/mkdirs.md @@ -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. \ No newline at end of file diff --git a/docs/f4pga/modules/synth.md b/docs/f4pga/modules/synth.md index 3910b00..5b200ad 100644 --- a/docs/f4pga/modules/synth.md +++ b/docs/f4pga/modules/synth.md @@ -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.