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

docs/f4pga: reorganise, add scope and references 

Signed-off-by: Unai Martinez-Corral <umartinezcorral@antmicro.com>
This commit is contained in:
Unai Martinez-Corral 2022-02-27 15:43:11 +01:00
parent 1b304a4271
commit 2ba01e787a
10 changed files with 112 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
docs/f4pga/CommonTargetsAndVariables.md
View File

@ -1,44 +0,0 @@
# sfbuild's common targets and values
Targets and values are named with some conventions.
Below are lists of the target and value names along with their meanings"
## Common targets that need to be provided by the user:
| Target name | list | Description |
|-------------|:----:|-------------|
| `sources` | yes | Verilog sources |
| `sdc` | no | Synopsys Design Constraints |
| `xdc` | yes | Xilinx Design Constraints (available only for Xilinx platforms) |
| `pcf` | no | Physical Constraints File |
## Commonly requested targets (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 |
## Built-in values
| Value name | type | Description |
|------------|------|-------------|
| `shareDir` | `string` | Path to symbiflow'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 |
## Values commonly 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. |

51
docs/f4pga/GettingStarted.md → docs/f4pga/Usage.md
View File

@ -1,4 +1,4 @@
# sfbuild
# Usage
## Getting started
@ -28,8 +28,6 @@ flow completes. Look for a line like this one on stdout.:
Target `bitstream` -> build/arty_35/top.bit
```
-------------------------------------------------------------------------------------
## Fundamental concepts
If you want to create a new sfbuild project, it's highly recommended that you
@ -142,7 +140,7 @@ here and there.
Typically **projects's flow configuration** will be used to resolve dependencies
for _HDL source code_ and _device constraints_.
## Using sfbuild to build a target
## Build a target
To build a **target** "`target_name`", use the following command:
```
@ -313,3 +311,48 @@ colon:
In the example above file `counter.v` has been modified and is now marked as
"**N**". This couses a bunch of other dependencies to be reqbuilt ("**R**").
`build_dir` and `xdc` were already present, so they are marked as "**O**".
## Common targets and values
Targets and values are named with some conventions.
Below are lists of the target and value names along with their meanings"
### Need to be provided by the user
| Target name | list | Description |
|-------------|:----:|-------------|
| `sources` | yes | Verilog sources |
| `sdc` | no | Synopsys Design Constraints |
| `xdc` | yes | Xilinx Design Constraints (available only for Xilinx platforms) |
| `pcf` | no | Physical Constraints File |
### 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 |
### Built-in values
| Value name | type | Description |
|------------|------|-------------|
| `shareDir` | `string` | Path to symbiflow'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 |
### 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. |

9
docs/f4pga/common/index.rst
View File

@ -1,9 +0,0 @@
Modules
#######
.. toctree::
generic_script_wrapper
io_rename
mkdirs
synth

27
docs/f4pga/index.rst Normal file
View File

@ -0,0 +1,27 @@
Overview
########
Python F4PGA is a package containing multiple modules to facilitate the usage of all the tools integrated in the F4PGA
ecosystem, and beyond.
The scope of Python F4PGA is threefold:
* Provide a fine-grained *pythonic* interface to the tools and utilities available as either command-line interfaces
(CLIs) or application proggraming interfaces (APIs) (either web or through shared libraries).
* Provide a CLI entrypoint covering the whole flows for end-users to produce bitstreams from HDL and/or software sources.
* Provide a CLI entrypoint for developers contributing to bitstream documentation and testing (continuous integration).
.. ATTENTION::
This is work-in-progress to adapt and organize the existing shell/bash based plumbing from multiple F4PGA repositories.
Therefore, it's still a *pre-alpha* and the codebase, commands and flows are subject to change.
It is strongly suggested not to rely on Python F4PGA until this note is updated/removed.
References
==========
* :gh:`chipsalliance/fpga-tool-perf#390@issuecomment-1023487178 <chipsalliance/fpga-tool-perf/pull/390#issuecomment-1023487178>`
* :ghsharp:`2225`
* :ghsharp:`2371`
* :ghsharp:`2455`
* `F4PGA GSoC 2022 project ideas: Generalization of wrapper scripts for installed F4PGA toolchain and making them OS agnostic <https://github.com/f4pga/ideas/blob/master/gsoc-2022-ideas.md#generalization-of-wrapper-scripts-for-installed-f4pga-toolchain-and-making-them-OS-agnostic>`__
* :gh:`FuseSoc <olofk/fusesoc>` | :gh:`Edalize <olofk/edalize>`
* `Electronic Design Automation Abstraction (EDA²) <https://edaa-org.github.io/>`__

0
docs/f4pga/common/generic_script_wrapper.md → docs/f4pga/modules/generic_script_wrapper.md
View File

33
docs/f4pga/Module.md → docs/f4pga/modules/index.md
View File

@ -1,10 +1,12 @@
# sfbuild modules interface
# Modules
## Interface
This document contains all the information needed to configure modules for
your _**sfbuild**_ project as well as some info about the API used to write
modules.
## Configuration interface:
### Configuration interface:
Modules are configured through an internal API by _**sfbuild**_.
The basic requirement for a module script is to expose a class with `Module`
@ -29,7 +31,7 @@ A _module configuration_ is a structure with the following fields:
The keys are value's names and the values can have any type.
* `platform` - Platform's name. This is a string.
## Platform-level configuration
### Platform-level configuration
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.
@ -47,7 +49,7 @@ Defining dictionaries for `takes` and `produces` is disallowed within
For a detailed look on the concepts described here, please have a look at
`sfbuild/platforms/xc7a50t`
## Project-level configuration
### Project-level configuration
Similarly to **platform's flow definition**, `values` dict can be provided.
The values provided there will overwrite the values from
@ -79,7 +81,7 @@ 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.
## Internal environmental variables
### Internal environmental variables
It's very usefule to be able to refer to some data within
**platform's flow definition** and **project's flow configuration** to
@ -149,7 +151,7 @@ categories:
* `python3` - path to Python 3 interpreter.
* `noisyWarnings` - (this one should probably get removed)
## `Module` class
### `Module` class
Each nmodule is represented as a class derived from `Module` class.
@ -165,14 +167,14 @@ Each module script should expose the class by defining it's name/type alias as
`ModuleClass`. sfbuild tries to access a `ModuleClass` attribute within a package
when instantiating a module.
## Module's execution modes
### Module's execution modes
A module ahas essentially two execution modes:
* _mapping_ mode
* _exec_ mode
### _mapping_ mode
#### _mapping_ mode
In _mapping_ mode the module is provided with an incomplete configuration which
includes:
@ -192,7 +194,7 @@ It should be noted that variables referring to the output dependencies
can't be accessed at this stage for the obvious reason as their values are yet
to be evaluated.
### _exec_ mode
#### _exec_ mode
In _exec_ mode the module does the actual work.
@ -210,7 +212,7 @@ The configuration passed into this mode is full and it includes:
When the module finishes executing in _exec_ mode, all of the dependencies
described in `outputs` should be present.
## Module initialization/instantiation
### Module initialization/instantiation
In the the `__init__` method of module's class, the following fields should be
set:
@ -222,7 +224,7 @@ set:
* `prod_meta` - A dictionary which maps product names to descriptions of these
products.
### Qualifiers/decorators
#### Qualifiers/decorators
By default the presence of all the dependencies and values is mandatory
(In case of `produces` that means that the module always has to produce the listed
@ -242,3 +244,12 @@ ways:
Currently it's impossible to combine both '`!`' and '`?`' together. This limitation
does not have any reason behind it other than the way the qualifier system
is implemented at the moment. It might be removed in the future.
## Common modules
```{toctree}
generic_script_wrapper
io_rename
mkdirs
synth
```

0
docs/f4pga/common/io_rename.md → docs/f4pga/modules/io_rename.md
View File

0
docs/f4pga/common/mkdirs.md → docs/f4pga/modules/mkdirs.md
View File

0
docs/f4pga/common/synth.md → docs/f4pga/modules/synth.md
View File

9
docs/index.rst
View File

@ -44,13 +44,12 @@ The project aims to design tools that are highly extendable and multiplatform.
.. toctree::
:caption: pyF4PGA Reference
:caption: Python utils
:maxdepth: 2
f4pga/GettingStarted
f4pga/CommonTargetsAndVariables
f4pga/Module
f4pga/common/index
f4pga/index
f4pga/Usage
f4pga/modules/index
f4pga/DevNotes