hw(docs): Add documentation in the form of comments

pulp-platform · Sep 13, 2024 · 6bf3243 · 6bf3243
1 parent 0fa7a83
commit 6bf3243
Show file tree

Hide file tree

Showing 5 changed files with 262 additions and 54 deletions.
diff --git a/hw/floo_axi_chimney.sv b/hw/floo_axi_chimney.sv
@@ -11,37 +11,54 @@
 
 /// A bidirectional network interface for connecting AXI4 Buses to the NoC
 module floo_axi_chimney #(
-  /// AXI parameter config
+  /// Config of the AXI interfaces (see floo_pkg::axi_cfg_t for details)
   parameter floo_pkg::axi_cfg_t AxiCfg = '0,
-  /// Route config
-  parameter floo_pkg::route_cfg_t RouteCfg  = floo_pkg::RouteDefaultCfg,
-  /// Chimney config
+  /// Config of the data path in the chimney (see floo_pkg::chimney_cfg_t for details)
   parameter floo_pkg::chimney_cfg_t ChimneyCfg = floo_pkg::ChimneyDefaultCfg,
+  /// Config for routing information (see floo_pkg::route_cfg_t for details)
+  parameter floo_pkg::route_cfg_t RouteCfg  = floo_pkg::RouteDefaultCfg,
   /// Atomic operation support
   parameter bit AtopSupport                 = 1'b1,
   /// Maximum number of oustanding Atomic transactions,
   /// must be smaller or equal to 2**AxiOutIdWidth-1 since
   /// Every atomic transactions needs to have a unique ID
   /// and one ID is reserved for non-atomic transactions
   parameter int unsigned MaxAtomicTxns      = 1,
-  // All the types
-  parameter type sam_rule_t                 = logic,
-  parameter type hdr_t                      = logic,
-  parameter sam_rule_t [RouteCfg.NumSamRules-1:0] Sam  = '0,
+  /// Node ID type for routing
+  parameter type id_t                                   = logic,
+  /// RoB index type for reordering.
+  // (can be ignored if `RoBType == NoRoB`)
+  parameter type rob_idx_t                              = logic,
+  /// Route type for source-based routing
+  /// (only used if `RouteCfg.RouteAlgo == SourceRouting`)
+  parameter type route_t                                = logic,
+  /// Header type for the flits
+  parameter type hdr_t                                  = logic,
+  /// Rule type for the System Address Map
+  /// (only used if `RouteCfg.UseIdTable == 1'b1`)
+  parameter type sam_rule_t                             = logic,
+  /// The System Address Map (SAM) rules
+  /// (only used if `RouteCfg.UseIdTable == 1'b1`)
+  parameter sam_rule_t [RouteCfg.NumSamRules-1:0] Sam   = '0,
+  /// AXI manager request channel type
   parameter type axi_in_req_t               = logic,
+  /// AXI manager response channel type
   parameter type axi_in_rsp_t               = logic,
+  /// AXI subordinate request channel type
   parameter type axi_out_req_t              = logic,
+  // AXI subordinate response channel type
   parameter type axi_out_rsp_t              = logic,
-  parameter type rob_idx_t                  = logic,
-  parameter type id_t                       = logic,
-  parameter type route_t                    = logic,
+  /// Floo `req` link type
   parameter type floo_req_t                 = logic,
+  /// Floo `rsp` link type
   parameter type floo_rsp_t                 = logic,
+  /// SRAM configuration type
   parameter type sram_cfg_t                 = logic
 ) (
   input  logic clk_i,
   input  logic rst_ni,
   input  logic test_enable_i,
+  /// SRAM configuration
   input  sram_cfg_t  sram_cfg_i,
   /// AXI4 side interfaces
   input  axi_in_req_t axi_in_req_i,
@@ -52,10 +69,10 @@ module floo_axi_chimney #(
   input  id_t id_i,
   /// Routing table for the current tile
   input  route_t [RouteCfg.NumRoutes-1:0] route_table_i,
-  /// Output to NoC
+  /// Output links to NoC
   output floo_req_t floo_req_o,
   output floo_rsp_t floo_rsp_o,
-  /// Input from NoC
+  /// Input links from NoC
   input  floo_req_t floo_req_i,
   input  floo_rsp_t floo_rsp_i
 );

diff --git a/hw/floo_nw_chimney.sv b/hw/floo_nw_chimney.sv
@@ -11,51 +11,77 @@
 
 /// A bidirectional network interface for connecting narrow & wide AXI Buses to the multi-link NoC
 module floo_nw_chimney #(
-  /// AXI parameter config
+  /// Config of the narrow AXI interfaces (see floo_pkg::axi_cfg_t for details)
   parameter floo_pkg::axi_cfg_t AxiCfgN = '0,
+  /// Config of the wide AXI interfaces (see floo_pkg::axi_cfg_t for details)
   parameter floo_pkg::axi_cfg_t AxiCfgW = '0,
-  // Chimney configs
+  /// Config of the narrow data path in the chimney (see floo_pkg::chimney_cfg_t for details)
   parameter floo_pkg::chimney_cfg_t ChimneyCfgN = floo_pkg::ChimneyDefaultCfg,
+  /// Config of the wide data path in the chimney (see floo_pkg::chimney_cfg_t for details)
   parameter floo_pkg::chimney_cfg_t ChimneyCfgW = floo_pkg::ChimneyDefaultCfg,
-  /// Route config
+  /// Config for routing information (see floo_pkg::route_cfg_t for details)
   parameter floo_pkg::route_cfg_t RouteCfg  = floo_pkg::RouteDefaultCfg,
   /// Atomic operation support, currently only implemented for
   /// the narrow network!
   parameter bit AtopSupport                      = 1'b1,
   /// Maximum number of oustanding Atomic transactions,
-  /// must be smaller or equal to 2**AxiOutIdWidth-1 since
+  /// must be smaller or equal to 2**`AxiCfgN.OutIdWidth`-1 since
   /// Every atomic transactions needs to have a unique ID
   /// and one ID is reserved for non-atomic transactions
   parameter int unsigned MaxAtomicTxns           = 1,
-  /// Type for implementation inputs and outputs
-  parameter type sam_rule_t                             = logic,
+  /// Node ID type for routing
+  parameter type id_t                                   = logic,
+  /// RoB index type for reordering.
+  // (can be ignored if `RoBType == NoRoB`)
+  parameter type rob_idx_t                              = logic,
+  /// Route type for source-based routing
+  /// (only used if `RouteCfg.RouteAlgo == SourceRouting`)
+  parameter type route_t                                = logic,
+  /// Header type for the flits
   parameter type hdr_t                                  = logic,
+  /// Rule type for the System Address Map
+  /// (only used if `RouteCfg.UseIdTable == 1'b1`)
+  parameter type sam_rule_t                             = logic,
+  /// The System Address Map (SAM) rules
+  /// (only used if `RouteCfg.UseIdTable == 1'b1`)
   parameter sam_rule_t [RouteCfg.NumSamRules-1:0] Sam   = '0,
+  /// Narrow AXI manager request channel type
   parameter type axi_narrow_in_req_t                    = logic,
+  /// Narrow AXI manager response channel type
   parameter type axi_narrow_in_rsp_t                    = logic,
+  /// Narrow AXI subordinate request channel type
   parameter type axi_narrow_out_req_t                   = logic,
+  /// Narrow AXI subordinate response channel type
   parameter type axi_narrow_out_rsp_t                   = logic,
+  /// Wide AXI manager request channel type
   parameter type axi_wide_in_req_t                      = logic,
+  /// Wide AXI manager response channel type
   parameter type axi_wide_in_rsp_t                      = logic,
+  /// Wide AXI subordinate request channel type
   parameter type axi_wide_out_req_t                     = logic,
+  /// Wide AXI subordinate response channel type
   parameter type axi_wide_out_rsp_t                     = logic,
-  parameter type rob_idx_t                              = logic,
-  parameter type id_t                                   = logic,
-  parameter type route_t                                = logic,
+  /// Floo `req` link type
   parameter type floo_req_t                             = logic,
+  /// Floo `rsp` link type
   parameter type floo_rsp_t                             = logic,
+  /// Floo `wide` link type
   parameter type floo_wide_t                            = logic,
+  /// SRAM configuration type `tc_sram_impl` in RoB
+  /// Only used if technology-dependent SRAM is used
   parameter type sram_cfg_t                             = logic
 ) (
   input  logic clk_i,
   input  logic rst_ni,
   input  logic test_enable_i,
+  /// SRAM configuration
   input  sram_cfg_t  sram_cfg_i,
-  /// AXI4 side interfaces
+  /// Narrow AXI4 side interfaces
   input  axi_narrow_in_req_t axi_narrow_in_req_i,
   output axi_narrow_in_rsp_t axi_narrow_in_rsp_o,
   output axi_narrow_out_req_t axi_narrow_out_req_o,
   input  axi_narrow_out_rsp_t axi_narrow_out_rsp_i,
+  /// Wide AXI4 side interfaces
   input  axi_wide_in_req_t axi_wide_in_req_i,
   output axi_wide_in_rsp_t axi_wide_in_rsp_o,
   output axi_wide_out_req_t axi_wide_out_req_o,
@@ -64,11 +90,11 @@ module floo_nw_chimney #(
   input  id_t id_i,
   /// Routing table for the current tile
   input  route_t [RouteCfg.NumRoutes-1:0] route_table_i,
-  /// Output to NoC
+  /// Output links to NoC
   output floo_req_t   floo_req_o,
   output floo_rsp_t   floo_rsp_o,
   output floo_wide_t  floo_wide_o,
-  /// Input from NoC
+  /// Input links from NoC
   input  floo_req_t   floo_req_i,
   input  floo_rsp_t   floo_rsp_i,
   input  floo_wide_t  floo_wide_i

diff --git a/hw/floo_nw_router.sv b/hw/floo_nw_router.sv
@@ -9,33 +9,52 @@
 
 /// Wrapper of a multi-link router for narrow and wide links
 module floo_nw_router #(
+  /// Config of the narrow AXI interfaces (see floo_pkg::axi_cfg_t for details)
   parameter floo_pkg::axi_cfg_t AxiCfgN       = '0,
+  /// Config of the wide AXI interfaces (see floo_pkg::axi_cfg_t for details)
   parameter floo_pkg::axi_cfg_t AxiCfgW       = '0,
+  /// Routing algorithm
   parameter floo_pkg::route_algo_e RouteAlgo  = floo_pkg::XYRouting,
+  /// Number of input/output ports
   parameter int unsigned NumRoutes            = 0,
+  /// Number of input ports
   parameter int unsigned NumInputs            = NumRoutes,
+  /// Number of output ports
   parameter int unsigned NumOutputs           = NumRoutes,
+  /// Input buffer depth
   parameter int unsigned InFifoDepth          = 0,
+  /// Output buffer depth
   parameter int unsigned OutFifoDepth         = 0,
+  /// Disable illegal connections in router
+  /// (only applies for `RouteAlgo == XYRouting`)
   parameter bit          XYRouteOpt           = 1'b1,
-  /// Used for ID-based and XY routing
-  parameter int unsigned IdWidth              = 0,
-  parameter type id_t                         = logic[IdWidth-1:0],
+  /// Node ID type
+  parameter type id_t                         = logic,
+  /// Header type
   parameter type hdr_t                        = logic,
-  /// Used for ID-based routing
+  /// Number of rules in the route table
+  /// (only used for `RouteAlgo == IdTable`)
   parameter int unsigned NumAddrRules         = 0,
-  parameter type         addr_rule_t          = logic,
+  /// Address rule type
+  /// (only used for `RouteAlgo == IdTable`)
+  parameter type addr_rule_t                  = logic,
+  /// Floo `req` link type
   parameter type floo_req_t                   = logic,
+  /// Floo `rsp` link type
   parameter type floo_rsp_t                   = logic,
+  /// Floo `wide` link type
   parameter type floo_wide_t                  = logic
 ) (
   input  logic   clk_i,
   input  logic   rst_ni,
   input  logic   test_enable_i,
-
+  /// Coordinate of the current node
+  /// (only used for `RouteAlgo == XYRouting`)
   input  id_t id_i,
+  /// Routing table
+  /// (only used for `RouteAlgo == IdTable`)
   input  addr_rule_t [NumAddrRules-1:0] id_route_map_i,
-
+  /// Input and output links
   input   floo_req_t [NumInputs-1:0] floo_req_i,
   input   floo_rsp_t [NumOutputs-1:0] floo_rsp_i,
   output  floo_req_t [NumOutputs-1:0] floo_req_o,
@@ -110,7 +129,6 @@ module floo_nw_router #(
     .OutFifoDepth     ( OutFifoDepth            ),
     .RouteAlgo        ( RouteAlgo               ),
     .XYRouteOpt       ( XYRouteOpt              ),
-    .IdWidth          ( IdWidth                 ),
     .id_t             ( id_t                    ),
     .NumAddrRules     ( NumAddrRules            ),
     .addr_rule_t      ( addr_rule_t             )
@@ -138,7 +156,6 @@ module floo_nw_router #(
     .OutFifoDepth     ( OutFifoDepth            ),
     .RouteAlgo        ( RouteAlgo               ),
     .XYRouteOpt       ( XYRouteOpt              ),
-    .IdWidth          ( IdWidth                 ),
     .flit_t           ( floo_rsp_generic_flit_t ),
     .id_t             ( id_t                    ),
     .NumAddrRules     ( NumAddrRules            ),
@@ -167,7 +184,6 @@ module floo_nw_router #(
     .OutFifoDepth     ( OutFifoDepth              ),
     .RouteAlgo        ( RouteAlgo                 ),
     .XYRouteOpt       ( XYRouteOpt                ),
-    .IdWidth          ( IdWidth                   ),
     .id_t             ( id_t                      ),
     .NumAddrRules     ( NumAddrRules              ),
     .addr_rule_t      ( addr_rule_t               )