Update docs, add minor type fixes

docs/source/description_files.md

@@ -72,10 +72,9 @@ external: # specify names of external ports and interfaces of the top module
   interfaces:
     in:
       - {ext_iface_name}
+    # note that `inout:` is invalid in the interfaces section
 ```
 
-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.
-
 `inout` ports are handled differently than `in` and `out` ports. When any IP has an inout port or when a hierarchy has an inout port specified in its `external.ports.inout` section, it must be included in `external.ports.inout` section of the parent design by specifying the name of the IP/hierarchy and port name that contains it. Name of the external port will be identical to the one in the IP core. In case of duplicate names a suffix `$n` is added (where `n` is a natural number) to the name of the second and subsequent duplicate names. `inout` ports cannot be connected to each other.
 
 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.

docs/source/hierarchies.md

@@ -13,6 +13,10 @@ Format is as follows:
 ```yaml
 hierarchies:
     {hierarchy_name_1}:
+      ips: # ips that are used on this hierarchy level
+        {ip_name}:
+          ...
+
       design:
         parameters:
           ...
@@ -37,4 +41,4 @@ hierarchies:
       ...
 ```
 
-More complex hierarchy example can be found in [examples/hierarchies](https://github.com/antmicro/topwrap/tree/main/examples/hierarchies).
+More complex hierarchy example can be found in [examples/hierarchies](https://github.com/antmicro/topwrap/tree/main/examples/hierarchy).

topwrap/common_serdes.py

@@ -4,7 +4,17 @@
 import itertools
 import re
 from dataclasses import field
-from typing import Any, Dict, Iterable, List, Mapping, Sequence, TypeVar, Union
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    List,
+    Mapping,
+    Sequence,
+    TypeVar,
+    Union,
+)
 
 import marshmallow
 import marshmallow_dataclass
@@ -212,7 +222,9 @@ def keyfunc(elem):
     return res
 
 
-def optional_with(default_factory: Any, meta_kw: Mapping[str, Any] = {}, **kwargs: Any):
+def optional_with(
+    default_factory: Callable[[], Any], meta_kw: Mapping[str, Any] = {}, **kwargs: Any
+):
     """
     A shorthand specification for a marshmallow_dataclasses field to be optional and default initialized
 

topwrap/design.py

@@ -107,7 +107,7 @@ class Slave:
 @marshmallow_dataclass.dataclass(frozen=True)
 class DesignSection:
     name: Optional[str] = optional_with(
-        None
+        lambda: None
     )  # This field is relevant only for the top-level design section
     parameters: Dict[str, Dict[str, IPCoreParameter]] = optional_with(dict)
     ports: DS_PortsT = optional_with(dict)

topwrap/design_to_kpm_dataflow_parser.py

@@ -289,7 +289,7 @@ def get_kpm_nodes_from_design(
     design = design_descr.design
     parameters = design.parameters
     for ip_name in design_descr.ips:
-        ports = design.ports[ip_name]
+        ports = design.ports.get(ip_name)
         ip_type = design_descr.ips[ip_name].path.stem
         spec_node = _get_specification_node_by_type(ip_type, specification)
         if spec_node is None:
@@ -311,8 +311,8 @@ def get_kpm_nodes_from_design(
             dir = interface["direction"]
             value = (
                 None
-                if ((dir != "input") or ("iface" in interface["type"][0]))
-                else ports[interface["name"]]
+                if ((dir != "input") or ("iface" in interface["type"][0])) or ports is None
+                else ports.get(interface["name"])
             )
             interfaces.append(KPMDataflowNodeInterface(interface["name"], dir, value))