floogen: Separate generated SV package and top-module (#110)

* floogen(utils): Update warning messages

* floogen(pkg): Support package-only creation

* docs: Update CHANGELOG

* docs: Update CHANGELOG

* docs: Update CHANGELOG with links to corresponding PRs

* bender: Add new generated packages to `Bender.yml`

* bender: Use `floo_test` target to avoid import of testbenches

Author: fischeti

Bender.yml

@@ -59,7 +59,7 @@ sources:
   - hw/floo_nw_vc_chimney.sv
   - hw/floo_nw_vc_router.sv
 
-  - target: test
+  - target: floo_test
     include_dirs:
       - hw/test/include
     files:
@@ -80,16 +80,18 @@ sources:
       - hw/tb/tb_floo_rob.sv
       - hw/tb/tb_floo_vc_router.sv
 
-  - target: all(test, axi_mesh)
+  - target: all(floo_test, axi_mesh)
     include_dirs:
       - hw/test/include
     files:
+      - generated/floo_axi_mesh_noc_pkg.sv
       - generated/floo_axi_mesh_noc.sv
       - hw/tb/tb_floo_axi_mesh.sv
 
-  - target: all(test, nw_mesh)
+  - target: all(floo_test, nw_mesh)
     include_dirs:
       - hw/test/include
     files:
+      - generated/floo_nw_mesh_noc_pkg.sv
       - generated/floo_nw_mesh_noc.sv
       - hw/tb/tb_floo_nw_mesh.sv

CHANGELOG.md

@@ -9,69 +9,72 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ### Added
 
 #### Hardware
-- The `floo_pkg` was extended with helper functions to calculate the size of AXI payloads and mapping of AXI to Floo Channels.
-- Multiple configuration structs were introduced to enable a more flexible and non-verbose configuration of the FlooNoC modules.
+- The `floo_pkg` was extended with helper functions to calculate the size of AXI payloads and mapping of AXI to Floo Channels. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- Multiple configuration structs were introduced to enable a more flexible and non-verbose configuration of the FlooNoC modules. (https://github.com/pulp-platform/FlooNoC/pull/65)
   - The `AxiCfg` describes all the necessary parameters needed for the type definitions of a bidirectional AXI interface
   - The `RouteCfg` describes all the necessary routing information parameters required by the chimneys.
   - The `ChimneyCfg` describes all other parameters for the data path of the chimney (e.g. Mgr/Sbr port enable, number of oustanding transactions, RoB types & sizes, etc.)
-- The `floo_test_pkg` now defines default configurations for all the new configuration structs that are used by the testbenches.
-- Add `floo_axi_router` module, which is a wrapper similar to the `floo_nw_router` but for single-AXI configurations, and can be used in conjunction with `floo_axi_chimney`.
+- The `floo_test_pkg` now defines default configurations for all the new configuration structs that are used by the testbenches. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- Add `floo_axi_router` module, which is a wrapper similar to the `floo_nw_router` but for single-AXI configurations, and can be used in conjunction with `floo_axi_chimney`. (https://github.com/pulp-platform/FlooNoC/pull/69)
 - `floo_nw_join` now also allows to convert to a narrow AXI interface, which is useful for accessing peripherals for instance.
 - The atomic adapter in `floo_nw_join` can now be disabled with `EnAtopAdapter`.
 
 #### FlooGen
-- The `data_width` and `user_width` fields for `protocols` are now also validated to be compatible with each other.
-- All the various `*Cfg`'s is now rendered by _FlooGen_, either in the `*_noc_pkg` or in the `*_noc` module itself.
-- Added support for single-AXI configuration networks.
-- Support for negative increments when specifying a `src_range` or `dst_range` in the `connections` schema.
-- Add support for multiple non-contiguous address ranges for endpoints.
+- The `data_width` and `user_width` fields for `protocols` are now also validated to be compatible with each other. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- All the various `*Cfg`'s is now rendered by _FlooGen_, either in the `*_noc_pkg` or in the `*_noc` module itself. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- Added support for single-AXI configuration networks. (https://github.com/pulp-platform/FlooNoC/pull/69)
+- Support for negative increments when specifying a `src_range` or `dst_range` in the `connections` schema. (https://github.com/pulp-platform/FlooNoC/pull/77)
+- Add support for multiple non-contiguous address ranges for endpoints. (https://github.com/pulp-platform/FlooNoC/pull/80)
 
 ### Changed
 
 #### Hardware
-- The `floo_narrow_wide_*` modules and the corresponding testbenches were renamed to `floo_nw_*` to be more concise.
-- The flit type definitions are now implemented as SystemVerilog macros in `typedef.svh`.
-- The parametrization of the chimney modules has changed dramatically. They now use the newly introduced `*Cfg`'s from the `floo_pkg`. In the narrow-wide chimneys, both datapaths now have their own configs (i.e. `*CfgN` and `*CfgW`), to reduce the verbosity of the module instantiation.
-- The payload field name in each `*_chan_t` type previously had its own name. This was unified to `payload` since `*_chan_t` already determines the type of the payload.
-- The input and output buffer FIFO depth of the routers were renamed to `InFifoDepth` and `OutFifoDepth` to be more consistent (previously `ChannelFifoDepth` and `OutputFifoDepth`).
-- The narrow-wide router wrapper now also requires the `AxiCfg` structs to redefine the link types internally.
-- The `ReorderBufferSize` parameters was shortened to `RoBSize`.
-- All testbenches were adapted to all changes.
-- All verification IPs were adapted to the new configuration structs.
+- The `floo_narrow_wide_*` modules and the corresponding testbenches were renamed to `floo_nw_*` to be more concise. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- The flit type definitions are now implemented as SystemVerilog macros in `typedef.svh`. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- The parametrization of the chimney modules has changed dramatically. They now use the newly introduced `*Cfg`'s from the `floo_pkg`. In the narrow-wide chimneys, both datapaths now have their own configs (i.e. `*CfgN` and `*CfgW`), to reduce the verbosity of the module instantiation. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- The payload field name in each `*_chan_t` type previously had its own name. This was unified to `payload` since `*_chan_t` already determines the type of the payload. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- The input and output buffer FIFO depth of the routers were renamed to `InFifoDepth` and `OutFifoDepth` to be more consistent (previously `ChannelFifoDepth` and `OutputFifoDepth`). (https://github.com/pulp-platform/FlooNoC/pull/65)
+- The narrow-wide router wrapper now also requires the `AxiCfg` structs to redefine the link types internally. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- The `ReorderBufferSize` parameters was shortened to `RoBSize`. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- All testbenches were adapted to all changes. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- All verification IPs were adapted to the new configuration structs. (https://github.com/pulp-platform/FlooNoC/pull/65)
 
 #### FlooGen
-- The link typedefs are now renderd with the macros in `typedef.svh` instead of rendering them in pure SystemVerilog.
-- The template files were renamed to use the more concise `nw` naming scheme.
-- The generated modules and packages of _FlooGen_ are now named `floo_*_noc` resp. `floo_*_noc_pkg` which is more consistent since all other modules have the `floo_*` prefix.
-- The `protocols` schema was adapted a bit to be more intuitive.
+- The link typedefs are now renderd with the macros in `typedef.svh` instead of rendering them in pure SystemVerilog. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- The template files were renamed to use the more concise `nw` naming scheme. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- The generated modules and packages of _FlooGen_ are now named `floo_*_noc` resp. `floo_*_noc_pkg` which is more consistent since all other modules have the `floo_*` prefix. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- The `protocols` schema was adapted a bit to be more intuitive. (https://github.com/pulp-platform/FlooNoC/pull/65)
   - The `type` field was renamed to `protocol`, which currently only accepts `AXI4`. A new `type` field now is used by _FlooGen_ to now where to attach the protocol in the network interface. Currently, _FlooGen_ only supports the narrow-wide AXI configuration, hence only `narrow|wide` is allowed as `type` values.
   - The `direction` field in the `protocol` schema is no longer required, since the direction is determined when specifying `mgr_port_protocol` and `sbr_port_protocol`.
   - The `name` field must be unique now, since it is used by `mgr_port_protocol` and `sbr_port_protocol` to reference the exact protocol.
   - All examples were adapted to reflect those changes.
-- A FlooGen configuration file now requires a `network_type` field, to determine the type of network to generate. The options are `axi` for single-AXI networks and `narrow-wide` for the narrow-wide AXI configurations.
-- The system address map `Sam` is now sorted correctly and can be indexed with `ep_id_e` values.
-- `id_offset` was renamed to `xy_id_offset`, since this is now only applicable in `XYRouting` networks. An ID offset does not make sense for other types of routing algorithms. The use of `id_offset` is anyway not recommended anymore, since the direction of the connections can be specified in the `connections` schema.
-- Endpoint names in the `ep_id_e` enum, which are created as 2D arrays now have clearer naming scheme by prefixing them with `X` and `Y`.
+- A _FlooGen_ configuration file now requires a `network_type` field, to determine the type of network to generate. The options are `axi` for single-AXI networks and `narrow-wide` for the narrow-wide AXI configurations.  (https://github.com/pulp-platform/FlooNoC/pull/69)
+- The system address map `Sam` is now sorted correctly and can be indexed with `ep_id_e` values. (https://github.com/pulp-platform/FlooNoC/pull/72)
+- `id_offset` was renamed to `xy_id_offset`, since this is now only applicable in `XYRouting` networks. An ID offset does not make sense for other types of routing algorithms. The use of `id_offset` is anyway not recommended anymore, since the direction of the connections can be specified in the `connections` schema. (https://github.com/pulp-platform/FlooNoC/pull/72)
+- Endpoint names in the `ep_id_e` enum, which are created as 2D arrays now have clearer naming scheme by prefixing them with `X` and `Y`. (https://github.com/pulp-platform/FlooNoC/pull/90)
+- The package and the top-module of the generated network are now seperated into its own modules `floo_*_noc.sv` and `floo_*_noc_pkg.sv`. (https://github.com/pulp-platform/FlooNoC/pull/110)
+- The `--only-pkg` and `-only-top` flags were added to the _FlooGen_ CLI to omit the generation of the package resp. the top-module. (https://github.com/pulp-platform/FlooNoC/pull/110)
+- If `--outdir` resp. `-o` is not specified _FlooGen_ will print the generated files to stdout instead of writing them to a file. (https://github.com/pulp-platform/FlooNoC/pull/110)
 
 ### Fixed
 
-- A bug in the calcuation of the RoB offset in `floo_rob` was fixed. Previously, the allocation and the write process used the same counter in bursts for offset calculation, which resulted in wrong offsets.
-- Routers with `XYRouting` do now use the global `id_offset`, which was previously not accounted for (or had to be specified manually).
-- Fixed elaboration errors in the chimneys that occured.
-- Fixed Synopsys DC elaboration error due to concatenation in `id_i` port connection of chimneys and routers.
+- A bug in the calcuation of the RoB offset in `floo_rob` was fixed. Previously, the allocation and the write process used the same counter in bursts for offset calculation, which resulted in wrong offsets. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- Routers with `XYRouting` do now use the global `id_offset`, which was previously not accounted for (or had to be specified manually). (https://github.com/pulp-platform/FlooNoC/pull/72)
+- Fixed elaboration errors in the chimneys that occured. (https://github.com/pulp-platform/FlooNoC/pull/75)
+- Fixed Synopsys DC elaboration error due to concatenation in `id_i` port connection of chimneys and routers. (https://github.com/pulp-platform/FlooNoC/pull/103)
 
 ### Removed
 
 #### Hardware
 
-- As the flit type definitions were moved to `typedef.svh`, the auto-generated `floo_*_pkg` packages were removed from the repository. Furthermore, all the (global) imports of those packages in the modules were replaced by parameters.
-- The testbench `tb_floo_nw_chimney` was removed since it was neither used nor maintained anymore.
-- The `IdIsPort` routing algorithm was removed since it can only be used for routes over a single router. The same functionality can be achieved with the `SourceRouting` algorithm.
-- The `dma_mesh` testbench was removed in favor of `nw_mesh` and `axi_mesh` which use generated networks with _FlooGen_.
+- As the flit type definitions were moved to `typedef.svh`, the auto-generated `floo_*_pkg` packages were removed from the repository. Furthermore, all the (global) imports of those packages in the modules were replaced by parameters. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- The testbench `tb_floo_nw_chimney` was removed since it was neither used nor maintained anymore. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- The `IdIsPort` routing algorithm was removed since it can only be used for routes over a single router. The same functionality can be achieved with the `SourceRouting` algorithm. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- The `dma_mesh` testbench was removed in favor of `nw_mesh` and `axi_mesh` which use generated networks with _FlooGen_. (https://github.com/pulp-platform/FlooNoC/pull/72)
 
 #### FlooGen
-- The package generation was removed from _FlooGen_ since it is now handled by the `typedef.svh` file. Further, the `--only-pkg` and `--pkg-outdir` flags were removed from the _FlooGen_ CLI.
-- The calculation of link sizes and AXI to Floo channel mapping was removed from the _FlooGen_ configuration file. This is now handled by the `floo_pkg` helper functions.
+- The package generation was removed from _FlooGen_ since it is now handled by the `typedef.svh` file. Further, the `--only-pkg` and `--pkg-outdir` flags were removed from the _FlooGen_ CLI. (https://github.com/pulp-platform/FlooNoC/pull/65)
+- The calculation of link sizes and AXI to Floo channel mapping was removed from the _FlooGen_ configuration file. This is now handled by the `floo_pkg` helper functions. (https://github.com/pulp-platform/FlooNoC/pull/65)
 
 ## [0.5.0] - 2024-09-13
 

Makefile

@@ -36,6 +36,7 @@ VLOGAN  	  ?= vcs-2022.06 vlogan
 
 BENDER_FLAGS += -t rtl
 BENDER_FLAGS += -t test
+BENDER_FLAGS += -t floo_test
 BENDER_FLAGS += -t snitch_cluster
 BENDER_FLAGS += -t idma_test
 BENDER_FLAGS := $(BENDER_FLAGS) $(EXTRA_BENDER_FLAGS)

floogen/floo_gen.py

@@ -25,7 +25,24 @@ def parse_args():
         "--outdir",
         type=Path,
         required=False,
-        help="Path to the output directory of the generated output.",
+        help=(
+            "Path to the output directory of the generated output files. "
+            "If not specified, the files are printed to stdout."
+        ),
+    )
+    parser.add_argument(
+        "--only-pkg",
+        dest="only_pkg",
+        action="store_true",
+        default=False,
+        help="Only generate the NoC package.",
+    )
+    parser.add_argument(
+        "--only-top",
+        dest="only_top",
+        action="store_true",
+        default=False,
+        help="Only generate the NoC top-module.",
     )
     parser.add_argument(
         "--no-format",
@@ -43,35 +60,48 @@ def main(): # pylint: disable=too-many-branches
     args = parse_args()
     network = parse_config(Network, args.config)
 
-    if args.outdir:
-        outdir = Path(os.getcwd(), args.outdir)
-    else:
-        # default output directory
-        outdir = Path(os.getcwd(), "generated")
-
     network.create_network()
     network.compile_network()
     network.gen_routing_info()
 
+    # Create the output directory if it doesn't exist
+    if args.outdir:
+        outdir = Path(args.outdir)
+        if not outdir.is_absolute():
+            outdir = Path(os.getcwd(), outdir)
+        outdir.mkdir(parents=True, exist_ok=True)
+
     # Visualize the network graph
     if args.visualize:
-        if outdir:
+        if args.outdir:
             network.visualize(filename=outdir / (network.name + ".pdf"))
         else:
             network.visualize(savefig=False)
 
     # Generate the network description
+    rendered_pkg = network.render_package()
     rendered_top = network.render_network()
+
+    # Format the output if requested
     if not args.no_format:
         rendered_top = verible_format(rendered_top)
+        rendered_pkg = verible_format(rendered_pkg)
+
     # Write the network description to file or print it to stdout
-    if outdir:
-        outdir.mkdir(parents=True, exist_ok=True)
-        top_file_name = outdir / f"floo_{network.name}_noc.sv"
-        with open(top_file_name, "w+", encoding="utf-8") as top_file:
-            top_file.write(rendered_top)
+    if args.outdir:
+        if not args.only_top:
+            pkg_file_name = outdir / f"floo_{network.name}_noc_pkg.sv"
+            with open(pkg_file_name, "w+", encoding="utf-8") as pkg_file:
+                pkg_file.write(rendered_pkg)
+        if not args.only_pkg:
+            top_file_name = outdir / f"floo_{network.name}_noc.sv"
+            with open(top_file_name, "w+", encoding="utf-8") as top_file:
+                top_file.write(rendered_top)
     else:
-        print(rendered_top)
+        if not args.only_top:
+            print(rendered_pkg)
+        if not args.only_pkg:
+            print(rendered_top)
 
 
 if __name__ == "__main__":

floogen/model/network.py

@@ -36,7 +36,9 @@ class Network(BaseModel):  # pylint: disable=too-many-public-methods
     model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
 
     with as_file(files(floogen.templates).joinpath("floo_top_noc.sv.mako")) as _tpl_path:
-        tpl: ClassVar = Template(filename=str(_tpl_path))
+        noc_tpl: ClassVar = Template(filename=str(_tpl_path))
+    with as_file(files(floogen.templates).joinpath("floo_top_noc_pkg.sv.mako")) as _tpl_path:
+        pkg_tpl: ClassVar = Template(filename=str(_tpl_path))
 
     name: str
     description: Optional[str]
@@ -760,7 +762,11 @@ def render_ep_enum(self):
 
     def render_network(self):
         """Render the network in the generated code."""
-        return self.tpl.render(noc=self)
+        return self.noc_tpl.render(noc=self)
+
+    def render_package(self):
+        """Render the network package in the generated code."""
+        return self.pkg_tpl.render(noc=self)
 
     def visualize(self, savefig=True, filename: pathlib.Path = "network.png"):
         """Visualize the network graph."""

floogen/templates/floo_top_noc.sv.mako

@@ -7,44 +7,6 @@
 
 // AUTOMATICALLY GENERATED! DO NOT EDIT!
 
-`include "axi/typedef.svh"
-`include "floo_noc/typedef.svh"
-
-package floo_${noc.name}_noc_pkg;
-
-  import floo_pkg::*;
-
-  /////////////////////
-  //   Address Map   //
-  /////////////////////
-
-  ${noc.render_ep_enum()}
-
-  ${noc.routing.render_typedefs()}
-
-% if noc.routing.use_id_table:
-  ${noc.routing.sam.render(aw=noc.routing.addr_width)}
-% else:
-  localparam int unsigned NumSamRules = 1;
-  typedef logic sam_rule_t;
-  localparam sam_rule_t Sam = '0;
-% endif
-
-% if noc.routing.route_algo.value == "SourceRouting":
-  ${noc.render_ni_tables()}
-% endif
-
-  ${noc.routing.render_route_cfg(name="RouteCfg")}
-
-% for prot in noc.protocols:
-  ${prot.render_typedefs()}
-% endfor
-
-  ${noc.routing.render_hdr_typedef(network_type=noc.network_type)}
-  ${noc.render_link_typedefs()}
-
-endpackage
-
 module floo_${noc.name}_noc
   import floo_pkg::*;
   import floo_${noc.name}_noc_pkg::*;