update ac313b2

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: d2907907ab1a3ea812e08068fd339d26
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/cli.md.txt

@@ -0,0 +1,75 @@
+# Command-line Interface
+
+## Building design
+
+To run Topwrap, use:
+
+```
+python -m fpga_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 fpga_topwrap build --sources src --design project.yml
+```
+
+To implement the design for a specific FPGA chip, provide the part name:
+
+```
+python -m fpga_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.
+
+```
+./build_server.sh
+cd kenning-pipeline-manager
+./run
+```
+
+2. Run Topwrap's client application, that will connect to a running Pipeline Manager server app.
+
+```
+python -m fpga_topwrap kpm_client [-h ip_addr] [-p port] 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.
+
+(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 fpga_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 fpga_topwrap parse --iface wishbone --iface s_axi HDL_FILES
+
+python -m fpga_topwrap parse --iface-deduce HDL_FILES
+```
+
+To get help, use:
+
+```
+python -m fpga_topwrap [build|kpm_client|parse] --help
+```

_sources/description_files.md.txt

@@ -0,0 +1,250 @@
+(description-files)=
+
+# Description files
+
+(design-description)=
+
+## Design Description
+
+To create a complete, fully synthesizable design, a proper design file is needed.
+It's used to specify IP cores, set their parameters' values, describe hierarchies for the project,
+connect the IPs and hierarchies, and pick external ports (those which will be connected to physical I/O).
+
+You can see example design files in `examples` directory. The structure is as below:
+
+```yaml
+ips:
+  # specify relations between IPs names in the design yaml
+  # and IP cores description yamls and modules
+  {ip_instance_name}:
+    file: {path_to_yaml_file_of_the_ip}
+    module: {name_of_the_HDL_module}
+  ...
+
+design:
+  hierarchies: # specify hierarchies designs
+    {hierarchy_name_1}:
+      design:
+        parameters:
+          ...
+        ports: # ports connections internal to this hierarchy
+          ...
+        interfaces: # interfaces connections internal to this hierarchy
+          ...
+        {nested_hierarchy_name}:
+          ...
+      external:
+        # external ports and/or interfaces of this hierarchy; these can be
+        # referenced in the upper-level `ports`, `interfaces` or `external` section
+        ...
+    {hierarchy_name_2}:
+      ...
+
+  parameters: # specify IPs parameter values to be overridden
+    {ip_instance_name}:
+      {param_name} : {param_value}
+      ...
+
+  ports:
+    # specify incoming ports connections of an IP named `ip1_name`
+    {ip1_name}:
+      {port1_name} : [{ip2_name}, {port2_name}]
+      ...
+    # specify incoming ports connections of a hierarchy named `hier_name`
+    {hier_name}:
+      {port1_name} : [{ip_name}, {port2_name}]
+      ...
+    # specify external ports connections
+    {ip_instance_name}:
+      {port_name} : ext_port_name
+    ...
+
+  interfaces:
+    # specify incoming interfaces connections of `ip1_name` IP
+    {ip1_name}:
+      {iface1_name} : [{ip2_name}, {iface2_name}]
+      ...
+    # specify incoming interfaces connections of `hier_name` hierarchy
+    {hier_name}:
+      {iface1_name} : [{ip_name}, {iface2_name}]
+      ...
+    # specify external interfaces connections
+    {ip_instance_name}:
+      {iface_name} : ext_iface_name
+    ...
+
+external: # specify names of external ports and interfaces of the top module
+  ports:
+    out:
+      - {ext_port_name}
+    inout:
+      - {ext_port_name}
+  interfaces:
+    in:
+      - {ext_iface_name}
+```
+
+In order for an IP to be present in the generated design, it must be specified in `ports` or `interfaces` sections as a key. This means that even if it has no incoming connections from any other IP or hierarchy, the `ports` or `interfaces` sections must contain `ip_name: {}` entry.
+
+The design description yaml format allows creating hierarchical designs. In order to create a hierarchy, it suffices to add its name as a key in the `design` section and describe the hierarchy design "recursively" by using the same keys and values (`ports`, `parameters` etc.) as in the top-level design (see above). Hierarchies can be nested recursively, which means that you can create a hierarchy inside another one.
+
+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.
+
+(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`.
+Here's an example description of ports of Clock Crossing IP:
+
+```yaml
+# file: clock_crossing.yaml
+signals:
+    in:
+        - clkA
+        - A
+        - clkB
+    out:
+        - B
+```
+
+The previous example is enough to make use of any IP. However, in order to benefit from connecting whole interfaces at once, ports must belong to a named interface like in this example:
+
+```yaml
+#file: axis_width_converter.yaml
+s_axis:
+    interface: AXIStream
+    mode: slave
+    signals:
+        in:
+            TDATA: [s_axis_tdata, 63, 0]
+            TKEEP: [s_axis_tkeep, 7, 0]
+            TVALID: s_axis_tvalid
+            TLAST: s_axis_tlast
+            TID: [s_axis_tid, 7, 0]
+            TDEST: [s_axis_tdest, 7, 0]
+            TUSER: s_axis_tuser
+        out:
+            TREADY: s_axis_tready
+
+m_axis:
+    interface: AXIStream
+    mode: master
+    signals:
+        in:
+            TREADY: m_axis_tready
+        out:
+            TDATA: [m_axis_tdata, 31, 0]
+            TKEEP: [m_axis_tkeep, 3, 0]
+            TVALID: m_axis_tvalid
+            TLAST: m_axis_tlast
+            TID: [m_axis_tid, 7, 0]
+            TDEST: [m_axis_tdest, 7, 0]
+            TUSER: m_axis_tuser
+signals: # These ports don't belong to any interface
+    in:
+        - clk
+        - rst
+```
+
+Names `s_axis` and `m_axis` will be used to group the selected ports.
+Each signal in an interface has a name which must match with the signal it's supposed to be connected to, for example `TDATA: port_name` will be connected to `TDATA: other_port_name`.
+
+Note that you don't have to write IP core description yamls by hand. You can use Topwrap's `parse` command (see {ref}`Generating IP core description YAMLs <generating-ip-yamls>`) in order to generate yamls from HDL source files and then adjust the yaml to your needs.
+
+### Port widths
+
+The width of every port defaults to `1`.
+You can specify the width using this notation:
+
+```yaml
+s_axis:
+    interface: AXIStream
+    mode: slave
+    signals:
+        in:
+            TDATA: [s_axis_tdata, 63, 0] # 64 bits
+            ...
+            TVALID: s_axis_tvalid # defaults to 1 bit
+
+signals:
+    in:
+        - [gpio_io_i, 31, 0] # 32 bits
+```
+
+### Parameterization
+
+Port widths don't have to be hardcoded - you can use parameters to describe an IP core in a generic way.
+Values specified in IP core yamls can be overriden in a design description file (see {ref}`Design Description <design-description>`).
+
+```yaml
+parameters:
+    DATA_WIDTH: 8
+    KEEP_WIDTH: (DATA_WIDTH+7)/8
+    ID_WIDTH: 8
+    DEST_WIDTH: 8
+    USER_WIDTH: 1
+
+s_axis:
+    interface: AXI4Stream
+    mode: slave
+    signals:
+        in:
+            TDATA: [s_axis_tdata, DATA_WIDTH-1, 0]
+            TKEEP: [s_axis_tkeep, KEEP_WIDTH-1, 0]
+            ...
+            TID: [s_axis_tid, ID_WIDTH-1, 0]
+            TDEST: [s_axis_tdest, DEST_WIDTH-1, 0]
+            TUSER: [s_axis_tuser, USER_WIDTH-1, 0]
+```
+
+Parameters values can be integers or math expressions, which are evaluated using `numexpr.evaluate()`.
+
+(port-slicing)=
+
+### Port slicing
+
+You can also slice a port, to use some bits of the port as a signal that belongs to an interface.
+The example below means:
+
+`Port m_axi_bid of the IP core is 36 bits wide. Use bits 23..12 as the BID signal of AXI master named m_axi_1`
+
+```yaml
+m_axi_1:
+    interface: AXI
+    mode: master
+    signals:
+        in:
+            BID: [m_axi_bid, 35, 0, 23, 12]
+```
+
+(interface-description-files)=
+
+## Interface Description files
+
+Topwrap can use predefined interfaces which are descibed in YAML-formatted files.
+The interfaces you use don't have to be predefined, but it's possible to perform checks
+on whether all the mandatory signals are connected, when you use an interface definition.
+
+You can see an example file below:
+
+```yaml
+name: AXI4Stream
+port_prefix: AXIS
+signals:
+    required:
+        - TVALID
+        - TDATA
+        - TLAST
+        - TREADY
+    optional:
+        - TID
+        - TDEST
+        - TKEEP
+        - TSTRB
+        - TUSER
+```
+
+The name of an interface has to be unique. We also specify a prefix which will be used as a shortened identifier.

_sources/developers_guide/examples.md.txt

@@ -0,0 +1,21 @@
+## Examples
+
+:::{note}
+Basic usage of examples is explained in the {ref}`getting-started` section.
+:::
+
+Examples provided with this project should cover from very simple designs to complex fully synthesizable cores.
+They should be sorted by increasing complexity and number of used features, e.g:
+- 101: minimal base design
+- 102: introduce user to parameters
+- 103: introduce user to slicing
+- 104: introduce user to interfaces
+- 105: etc.
+
+Developers are encouraged to create/add new examples in the same spirit.
+Simple examples are used to teach how to use this tool and demonstrate its features.
+Real-world use cases are also welcome to prove that the implementation is mature enough to handle practical designs.
+
+:::{note}
+The goal of this project is not to create a library of cores and/or their functional validation. This need is fulfilled by projects like FuseSoC, SVUnit, etc.
+:::

_sources/developers_guide/setup.md.txt

@@ -0,0 +1,10 @@
+# Setup
+
+It is recommended for developers to keep code style and frequently run tests.
+In order to setup the developer's environment install python packages from `requirements.dev.txt`, which shall include `nox` and `pre-commit`:
+
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.dev.txt
+```