Unify usage into one file, unify description into one file

Unified hierarchies into design description
Unified pipeline manager into cli now renamed to using topwrap
desciption_files hierachies page changed
removed line link in user repo

Signed-off-by: gkierzkowski <[email protected]>

.flake8

@@ -15,6 +15,7 @@ exclude =
     venv,
     build,
     docs/source/conf.py,
+    workspace,
 count = True
 show-source = True
 statistics = True

.gitignore

@@ -136,3 +136,6 @@ dmypy.json
 
 # Cython debug symbols
 cython_debug/
+
+# NixOS shell config
+shell.nix

docs/source/description_files.md

@@ -1,6 +1,6 @@
 (description-files)=
 
-# Description files
+# Creating a design
 
 (design-description)=
 
@@ -17,13 +17,13 @@ ips:
   # specify relations between IPs instance names in the
   # design yaml and IP cores description yamls
   {ip_instance_name}:
-    file: {path_to_yaml_file_of_the_ip}
+    file: {path_to_ip_description}
   ...
 
 design:
   name: {design_name} # optional name of the toplevel
   hierarchies:
-      # see "Hierarchies" page for a detailed description of the format
+      # see "Hierarchies" below for a detailed description of the format
       ...
   parameters: # specify IPs parameter values to be overridden
     {ip_instance_name}:
@@ -80,17 +80,67 @@ The design description yaml format allows creating hierarchical designs. In orde
 
 Note that IPs and hierarchies names cannot be duplicated on the same hierarchy level. For example, the `design` section cannot contain two identical keys, but it's correct to have `ip_name` key in this section and `ip_name` in the `design` section of some hierarchy.
 
+
+(hierarchies)=
+### Hierarchies
+
+Hierarchies allow for creating designs with subgraphs in them.
+Subgraphs can contain multiple IP-cores and other subgraphs.
+This allows creating nested designs in topwrap.
+
+### Format
+
+All information about hierarchies is specified in [design description](description_files.md).
+`hierarchies` key must be a direct descendant of the `design` key.
+Format is as follows:
+
+```yaml
+hierarchies:
+    {hierarchy_name_1}:
+      ips: # ips that are used on this hierarchy level
+        {ip_name}:
+          ...
+
+      design:
+        parameters:
+          ...
+        ports: # ports connections internal to this hierarchy
+          # note that also you have to connect port to it's external port equivalent (if exists)
+          {ip1_name}:
+              {port1_name} : [{ip2_name}, {port2_name}]
+              {port2_name} : {port2_external_equivalent} # connection to external port equivalent. Note that it has to be to the parent port
+            ...
+        hierarchies:
+          {nested_hierarchy_name}:
+            # structure here will be the same as for {hierarchy_name_1}
+            ...
+      external:
+        # external ports and/or interfaces of this hierarchy; these can be
+        # referenced in the upper-level `ports`, `interfaces` or `external` section
+        ports:
+            in:
+              - {port2_external_equivalent}
+        ...
+    {hierarchy_name_2}:
+      ...
+```
+
+More complex hierarchy example can be found in [examples/hierarchy](https://github.com/antmicro/topwrap/tree/main/examples/hierarchy).
+
+
 (ip-description)=
 
 ## IP description files
 
 Every IP wrapped by Topwrap needs a description file in YAML format.
 
 The ports of an IP should be placed in global `signals` node, followed by the direction of `in`, `out` or `inout`.
+The module name of an IP should be placed in global `name` node, it should be consistent with how it is defined in HDL file.
 Here's an example description of ports of Clock Crossing IP:
 
 ```yaml
 # file: clock_crossing.yaml
+name: cdc_flag
 signals:
     in:
         - clkA
@@ -104,6 +154,7 @@ The previous example is enough to make use of any IP. However, in order to benef
 
 ```yaml
 #file: axis_width_converter.yaml
+name: axis_width_converter
 interfaces:
     s_axis:
         type: AXIStream

docs/source/index.md

@@ -6,11 +6,9 @@
 introduction
 getting_started
 description_files
-interconnect_gen
-cli
+usage
 user_repositories
-hierarchies
-pipeline_manager
+interconnect_gen
 fusesoc
 ```
 

docs/source/introduction.md

@@ -7,7 +7,7 @@ Topwrap is an open source command line toolkit for connecting individual HDL mod
 The toolkit is designed to take advantage of the ever-growing availability of open source digital logic designs and offers a user-friendly graphical interface which lets you mix-and-match GUI-driven design with CLI-based adjustments and present designs in a diagram form thanks to the integration with Antmicro’s [Pipeline Manager](https://github.com/antmicro/kenning-pipeline-manager).
 
 Topwrap's most notable features are:
+* User-friendly GUI
 * Parsing HDL design files with automatic recognition of common interfaces
 * Simple YAML-based description for command-line use
-* Capability to create a custom libraries for reuse across projects
-* User-friendly GUI powered by [Kenning Pipeline Manager](https://github.com/antmicro/kenning-pipeline-manager).
+* Capability to create custom libraries for reuse across projects

docs/source/pipeline_manager.md → docs/source/usage.md

@@ -1,10 +1,13 @@
-(kenning-pipeline-manager)=
+# Using topwrap
 
-# Kenning Pipeline Manager
+(GUI)=
+## GUI
 
 Topwrap can make use of [Kenning Pipeline Manager](https://github.com/antmicro/kenning-pipeline-manager) to visualize the process of creating block design.
 
-## Run Topwrap with Pipeline Manager
+(kenning-pipeline-manager)=
+
+### Run Topwrap with Pipeline Manager
 
 1. Build and run Pipeline Manager server
 
@@ -31,10 +34,9 @@ Topwrap can make use of [Kenning Pipeline Manager](https://github.com/antmicro/k
         topwrap/ips/axi/axi_axil_adapter.yaml \
         examples/pwm/ipcores/{litex_pwm.yml,ps7.yaml} -d examples/pwm/project.yml
     ```
-
 3. Create block design in Pipeline Manager
 
-    Upon successful connection to a Pipeline Manager server, Topwrap will generate and send to the server a specification describing the structure of previously selected IP cores. After that, you are free to create a custom block design by means of:
+    Upon successful connection to a Pipeline Manager server, Topwrap will generate and send to the server a specification describing the structure of previously selected IP cores. If the `-d` option was used a design will be shown in gui. From there you can create or modify designs by:
     * adding IP core instances to the block design. Each Pipeline Manager's node has `delete` and `rename` options, which make it possible to remove the selected node and change its name respectively. This means that you can create multiple instances of the same IP core.
     * adjusting IP cores' parameters values. Each node may have input boxes in which you can enter parameters' values (default parameter values are added while adding an IP core to the block design):
     ```{image} img/node_parameters.png
@@ -52,7 +54,7 @@ Topwrap can make use of [Kenning Pipeline Manager](https://github.com/antmicro/k
     ```{image} img/pwm_design.png
     ```
 
-## Pipeline Manager features
+### Pipeline Manager features
 
 While creating a custom block design, you can make use of the following Pipeline Manager's features:
 * export (save) design to a file
@@ -62,20 +64,20 @@ While creating a custom block design, you can make use of the following Pipeline
 
 (export-design)=
 
-### Export design to yaml description file
+#### Export design to yaml description file
 
 Created block design can be saved to a {ref}`design description file <design-description>` in yaml format, using Pipeline Manager's `Save file` option.
 Target location on the filesystem can then be browsed in a filesystem dialog window.
 
 (import-design)=
 
-### Import design from yaml description file
+#### Import design from yaml description file
 
 Topwrap also supports conversion in the opposite way - block design in Pipeline Manager can be generated from a yaml design description file using `Load file` feature.
 
 (validate-design)=
 
-### Design validation
+#### Design validation
 
 Pipeline Manager is capable of performing some basic checks at runtime such as interface type checking while creating a connection. However you can also run more complex tests by using Pipeline Manager's `Validate` option. Topwrap will then respond with a validity confirmation or error messages. The rules you need to follow in order to keep your block design valid are:
 * multiple IP cores with the same name are not allowed (except from external metanodes).
@@ -93,6 +95,61 @@ If a block design validation returns a warning, it means that the block design c
 
 (build-design)=
 
-### Building design
+#### Building design
 
 Once the design has been created and tested for validity, you can build design using `Run` button. If the design does not contain any errors, this will result in creating a top module in a directory where `topwrap kpm_client` was ran, similarly when using Topwrap's `topwrap build` command.
+
+## CLI
+
+Topwrap has a couple CLI only functions that expand gui functionality.
+
+(generating-ip-yamls)=
+### Generating IP core description YAMLs
+
+You can use Topwrap to generate ip core description yamls from HDL sources to use them in your `project.yml`.
+To learn how project and core yamls work check {ref}`design description <design-description>` and {ref}`ip description <ip-description>`
+
+```
+python -m topwrap parse HDL_FILES
+```
+
+In HDL source files, ports that belong to the same interface (e.g. wishbone or AXI),
+have often a common prefix, which corresponds to the interface name. If such naming
+convention is followed in the HDL sources, Topwrap can also divide ports into user-specified
+interfaces, or automatically deduce interfaces names when generating yaml file:
+
+```
+python -m topwrap parse --iface wishbone --iface s_axi HDL_FILES
+
+python -m topwrap parse --iface-deduce HDL_FILES
+```
+
+To get help, use:
+
+```
+python -m topwrap [build|kpm_client|parse] --help
+```
+
+(building-design)=
+
+### Building design
+
+Topwrap can build a synthesizable design from source files connected in a way described by a design file, to do this run:
+
+```
+python -m topwrap build --design project.yml
+```
+
+Where `project.yml` should be your file with description of the top module.
+
+You can specify a directory to be scanned for additional sources:
+
+```
+python -m topwrap build --sources src --design project.yml
+```
+
+To implement the design for a specific FPGA chip, provide the part name:
+
+```
+python -m topwrap build --sources src --design project.yml --part 'xc7z020clg400-3'
+```