diff --git a/.flake8 b/.flake8 index 78e7a430..5516512a 100644 --- a/.flake8 +++ b/.flake8 @@ -15,6 +15,7 @@ exclude = venv, build, docs/source/conf.py, + workspace, count = True show-source = True statistics = True diff --git a/.gitignore b/.gitignore index a81c8ee1..917418e7 100644 --- a/.gitignore +++ b/.gitignore @@ -136,3 +136,6 @@ dmypy.json # Cython debug symbols cython_debug/ + +# NixOS shell config +shell.nix diff --git a/docs/source/cli.md b/docs/source/cli.md deleted file mode 100644 index 148a6ceb..00000000 --- a/docs/source/cli.md +++ /dev/null @@ -1,76 +0,0 @@ -# Command-line Interface - -## Building design - -To run Topwrap, use: - -``` -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' -``` - -(connect-topwrap-to-pm)= - -## Connect Topwrap to Pipeline Manager - -If you want to use Pipeline Manager as a UI for creating block design, you need to: - -1. Build and run Pipeline Manager server application. - -``` -python -m topwrap kpm_build_server -python -m topwrap kpm_run_server -``` - -2. Run Topwrap's client application, that will connect to a running Pipeline Manager server app. - -``` -python -m topwrap kpm_client [-h ip_addr] [-p port] [-d FILE] FILES -``` - -Topwrap will then try to connect to the server running on `ip_addr:port` and send a specification generated from `FILES`, which should be IP core description yamls. - -If `-h` or `-p` options are not specified, ip address `127.0.0.1` and port `9000` will be chosen by default. - -If `-d` option is specified, kpm will start with specified design file loaded. - -(generating-ip-yamls)= - -## Generating IP core description YAMLs - -You can also use Topwrap to generate ip core description yamls from HDL sources, -that can be later used in your `project.yml`: - -``` -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 -``` diff --git a/docs/source/description_files.md b/docs/source/description_files.md index 799c32b0..93129b27 100644 --- a/docs/source/description_files.md +++ b/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,6 +80,54 @@ 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 @@ -87,10 +135,12 @@ Note that IPs and hierarchies names cannot be duplicated on the same hierarchy l 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 diff --git a/docs/source/hierarchies.md b/docs/source/hierarchies.md deleted file mode 100644 index 980cef99..00000000 --- a/docs/source/hierarchies.md +++ /dev/null @@ -1,44 +0,0 @@ -# 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). diff --git a/docs/source/index.md b/docs/source/index.md index cc608cd2..db269cc7 100644 --- a/docs/source/index.md +++ b/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 ``` diff --git a/docs/source/introduction.md b/docs/source/introduction.md index 8439715c..f3f982d4 100644 --- a/docs/source/introduction.md +++ b/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 diff --git a/docs/source/pipeline_manager.md b/docs/source/usage.md similarity index 77% rename from docs/source/pipeline_manager.md rename to docs/source/usage.md index 156ee7c7..bf7685c9 100644 --- a/docs/source/pipeline_manager.md +++ b/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 ` 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 ` and {ref}`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' +``` diff --git a/docs/source/user_repositories.md b/docs/source/user_repositories.md index f6a289a6..1508eef4 100644 --- a/docs/source/user_repositories.md +++ b/docs/source/user_repositories.md @@ -1,9 +1,8 @@ -# User repositories -Repositories allow for easy loading packages with IP-cores. +# Packaging multiple files -You can add repositories to be loaded each time topwrap is ran by specifying them in configuration file. +Repositories allow for easy packaging and loading multiple IP-cores and custom interfaces. -It has to be located in one of the following locations: +You can specify repositories to be loaded each time topwrap is ran by listing them in a configuration file that should be located in one of the following locations: ``` topwrap.yaml ~/.config/topwrap/topwrap.yaml @@ -14,11 +13,11 @@ Example contents of user config: ``` force_interface_compliance: true repositories: - - name: name of repo + - name: name_of_repo path: ~/path_to_repo/repo ``` -Topwrap provides internal API for constructing repositories in python code which can be [found here](https://github.com/antmicro/topwrap/blob/main/topwrap/repo/user_repo.py#L144) +Topwrap provides internal API for constructing repositories in python code which can be [found here](https://github.com/antmicro/topwrap/blob/main/topwrap/repo/user_repo.py) Structure of repository has to be as follows: ``` @@ -38,8 +37,10 @@ path_to_repository/ | interface1.yaml | interface2.yaml ``` -Repository has two main catalogs: `cores` and `interfaces`. Inside `cores` each core has it's own catalog with it's design file and `srcs` where are stored verilog/VHDL files. +Repository has two main directories: `cores` and `interfaces`. -There is optional interfaces catalog where can be stored interfaces for cores. +Inside `cores` each core has it's own directory with it's description file and `srcs` where the verilog/VHDL files are stored. + +The `interfaces` directory is optional, and contains interface description files. Example User Repo can be found in [examples/user_repository](https://github.com/antmicro/topwrap/tree/main/examples/user_repository). diff --git a/pyproject.toml b/pyproject.toml index 4435ee8a..a9960fcb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -91,6 +91,7 @@ exclude = ''' | __pycache__ | venv | build + | workspace )/ | docs/source/conf.py ) @@ -110,10 +111,11 @@ skip = [ "venv", "build", "docs/source/conf.py", + "workspace", ] [tool.codespell] -skip = "build,venv,cov_html,./tests/data,.git,.nox,__pycache__" +skip = "build,venv,cov_html,./tests/data,.git,.nox,__pycache__,workspace" ignore-words-list = "convertor, inout, inouts" [tool.pyright]