From 696acdb61ab68eb5ac4d2a404fa4dc7ab03a67f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Wolfgang=20R=C3=B6nninger?= <wroennin@student.ethz.ch>
Date: Fri, 4 Dec 2020 15:37:40 +0100
Subject: [PATCH] axi_xbar: Add port/param documentation

---
 src/axi_xbar.sv | 47 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 45 insertions(+), 2 deletions(-)

diff --git a/src/axi_xbar.sv b/src/axi_xbar.sv
index 7fd4f537d..bffa890fe 100644
--- a/src/axi_xbar.sv
+++ b/src/axi_xbar.sv
@@ -13,45 +13,88 @@
 // - Andreas Kurth <akurth@iis.ee.ethz.ch>
 // - Florian Zaruba <zarubaf@iis.ee.ethz.ch>
 
-// axi_xbar: Fully-connected AXI4+ATOP crossbar with an arbitrary number of slave and master ports.
-// See `doc/axi_xbar.md` for the documentation, including the definition of parameters and ports.
+/// axi_xbar: Fully-connected AXI4+ATOP crossbar with an arbitrary number of slave and master ports.
+/// See `doc/axi_xbar.md` for the documentation, including the definition of parameters and ports.
 module axi_xbar
 import cf_math_pkg::idx_width;
 #(
+  /// Configuration struct for the crossbar see `axi_pkg` for fields and definitions.
   parameter axi_pkg::xbar_cfg_t Cfg                                   = '0,
+  /// Enable atomic operations support.
   parameter bit  ATOPs                                                = 1'b1,
+  /// Connectivity matrix
   parameter bit [Cfg.NoSlvPorts-1:0][Cfg.NoMstPorts-1:0] Connectivity = '1,
+  /// AXI4+ATOP AW channel struct type for the slave ports.
   parameter type slv_aw_chan_t                                        = logic,
+  /// AXI4+ATOP AW channel struct type for the master ports.
   parameter type mst_aw_chan_t                                        = logic,
+  /// AXI4+ATOP W channel struct type for all ports.
   parameter type w_chan_t                                             = logic,
+  /// AXI4+ATOP B channel struct type for the slave ports.
   parameter type slv_b_chan_t                                         = logic,
+  /// AXI4+ATOP B channel struct type for the master ports.
   parameter type mst_b_chan_t                                         = logic,
+  /// AXI4+ATOP AR channel struct type for the slave ports.  
   parameter type slv_ar_chan_t                                        = logic,
+  /// AXI4+ATOP AR channel struct type for the master ports.
   parameter type mst_ar_chan_t                                        = logic,
+  /// AXI4+ATOP R channel struct type for the slave ports.  
   parameter type slv_r_chan_t                                         = logic,
+  /// AXI4+ATOP R channel struct type for the master ports.
   parameter type mst_r_chan_t                                         = logic,
+  /// AXI4+ATOP request struct type for the slave ports.
   parameter type slv_req_t                                            = logic,
+  /// AXI4+ATOP response struct type for the slave ports.
   parameter type slv_resp_t                                           = logic,
+  /// AXI4+ATOP request struct type for the master ports.
   parameter type mst_req_t                                            = logic,
+  /// AXI4+ATOP response struct type for the master ports
   parameter type mst_resp_t                                           = logic,
+  /// Address rule type for the address decoders from `common_cells:addr_decode`.
+  /// Example types are provided in `axi_pkg`.
+  /// Required struct fields:
+  /// ```
+  /// typedef struct packed {
+  ///   int unsigned idx;
+  ///   axi_addr_t   start_addr;
+  ///   axi_addr_t   end_addr;
+  /// } rule_t;
+  /// ```
   parameter type rule_t                                               = axi_pkg::xbar_rule_64_t
 `ifdef VCS
   , localparam int unsigned MstPortsIdxWidth =
       (Cfg.NoMstPorts == 32'd1) ? 32'd1 : unsigned'($clog2(Cfg.NoMstPorts))
 `endif
 ) (
+  /// Clock, positive edge triggered.
   input  logic                                                          clk_i,
+  /// Asynchronous reset, active low.  
   input  logic                                                          rst_ni,
+  /// Testmode enable, active high.
   input  logic                                                          test_i,
+  /// AXI4+ATOP requests to the slave ports.  
   input  slv_req_t  [Cfg.NoSlvPorts-1:0]                                slv_ports_req_i,
+  /// AXI4+ATOP responses of the slave ports.  
   output slv_resp_t [Cfg.NoSlvPorts-1:0]                                slv_ports_resp_o,
+  /// AXI4+ATOP requests of the master ports.  
   output mst_req_t  [Cfg.NoMstPorts-1:0]                                mst_ports_req_o,
+  /// AXI4+ATOP responses to the master ports.  
   input  mst_resp_t [Cfg.NoMstPorts-1:0]                                mst_ports_resp_i,
+  /// Address map array input for the crossbar. This map is global for the whole module.
+  /// It is used for routing the transactions to the respective master ports.
+  /// Each master port can have multiple different rules.
   input  rule_t     [Cfg.NoAddrRules-1:0]                               addr_map_i,
+  /// Enable default master port.
   input  logic      [Cfg.NoSlvPorts-1:0]                                en_default_mst_port_i,
 `ifdef VCS
+  /// Enables a default master port for each slave port. When this is enabled unmapped
+  /// transactions get issued at the master port given by `default_mst_port_i`.
+  /// When not used, tie to `'0`.  
   input  logic      [Cfg.NoSlvPorts-1:0][MstPortsIdxWidth-1:0]          default_mst_port_i
 `else
+  /// Enables a default master port for each slave port. When this is enabled unmapped
+  /// transactions get issued at the master port given by `default_mst_port_i`.
+  /// When not used, tie to `'0`.  
   input  logic      [Cfg.NoSlvPorts-1:0][idx_width(Cfg.NoMstPorts)-1:0] default_mst_port_i
 `endif
 );