axi_throttle: Add a module limiting the maximum number of outstanding…

… transfers downstream (pulp-platform#254)

* axi_throttle: Add a module that limits the maximum number of outstanding transfers sent to the
  downstream logic

Bender.yml

@@ -8,7 +8,7 @@ package:
     - "Wolfgang Roenninger <[email protected]>"
 
 dependencies:
-  common_cells: { git: "https://github.com/pulp-platform/common_cells.git", version: 1.21.0 }
+  common_cells: { git: "https://github.com/pulp-platform/common_cells.git", version: 1.26.0 }
   common_verification: { git: "https://github.com/pulp-platform/common_verification.git", version: 0.2.0 }
 
 export_include_dirs:
@@ -46,6 +46,7 @@ sources:
   - src/axi_modify_address.sv
   - src/axi_mux.sv
   - src/axi_serializer.sv
+  - src/axi_throttle.sv
   - src/axi_to_mem.sv
   # Level 3
   - src/axi_cdc.sv

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - `axi_to_mem`: AXI4+ATOP slave to control on chip memory.
 - `axi_test`: Add `mapped` mode to the random classes as well as additional functionality to the
   scoreboard class.
+- `axi_throttle`: Add a module that limits the maximum number of outstanding transfers sent to the
+  downstream logic.
 
 ### Changed
 

README.md

@@ -51,6 +51,7 @@ In addition to the documents linked in the following table, we are setting up [d
 | [`axi_mux`](src/axi_mux.sv)                          | Multiplexes the AXI4 slave ports down to one master port.                                         | [Doc](doc/axi_mux.md)          |
 | [`axi_pkg`](src/axi_pkg.sv)                          | Contains AXI definitions, common structs, and useful helper functions.                            |                                |
 | [`axi_serializer`](src/axi_serializer.sv)            | Serializes transactions with different IDs to the same ID.                                        |                                |
+| [`axi_throttle`](src/axi_throttle.sv)                | Limits the maximum number of outstanding transfers sent to the downstream logic.                  |                                |
 | [`axi_test`](src/axi_test.sv)                        | A set of testbench utilities for AXI interfaces.                                                  |                                |
 | [`axi_to_axi_lite`](src/axi_to_axi_lite.sv)          | AXI4 to AXI4-Lite protocol converter.                                                             |                                |
 | [`axi_to_mem`](src/axi_to_mem.sv)                    | AXI4 to memory protocol (req, gnt, rvalid) converter.                                             |                                |

axi.core

@@ -38,6 +38,7 @@ filesets:
       - src/axi_modify_address.sv
       - src/axi_mux.sv
       - src/axi_serializer.sv
+      - src/axi_throttle.sv
       - src/axi_to_mem.sv
       # Level 3
       - src/axi_cdc.sv
@@ -52,7 +53,7 @@ filesets:
       - src/axi_xbar.sv
     file_type : systemVerilogSource
     depend :
-      - ">=pulp-platform.org::common_cells:1.21.0"
+      - ">=pulp-platform.org::common_cells:1.26.0"
 
 generators:
   axi_intercon_gen:

ips_list.yml

@@ -1,5 +1,5 @@
 common_cells:
-    commit: v1.21.0
+    commit: v1.26.0
     group: pulp-platform
 
 common_verification:

src/axi_throttle.sv

@@ -0,0 +1,101 @@
+// Copyright 2022 ETH Zurich and University of Bologna.
+// Solderpad Hardware License, Version 0.51, see LICENSE for details.
+// SPDX-License-Identifier: SHL-0.51
+//
+// Thomas Benz <[email protected]>
+
+/// Throttles an AXI4+ATOP bus. The maximum number of outstanding transfers have to
+/// be set as a compile-time parameter, whereas the number of outstanding transfers can be set
+/// during runtime. This module assumes either in-order processing of the requests or
+/// indistinguishability of the request/responses (all ARs and AWs have the same ID respectively).
+module axi_throttle #(
+    /// The maximum amount of allowable outstanding write requests
+    parameter int unsigned MaxNumAwPending = 1,
+    /// The maximum amount of allowable outstanding read requests
+    parameter int unsigned MaxNumArPending = 1,
+    /// AXI4+ATOP request type
+    parameter type axi_req_t = logic,
+    /// AXI4+ATOP response type
+    parameter type axi_rsp_t = logic,
+    /// The width of the write credit counter (*DO NOT OVERWRITE*)
+    parameter int unsigned WCntWidth = cf_math_pkg::idx_width(MaxNumAwPending),
+    /// The width of the read credit counter (*DO NOT OVERWRITE*)
+    parameter int unsigned RCntWidth = cf_math_pkg::idx_width(MaxNumArPending),
+    /// The type of the write credit counter (*DO NOT OVERWRITE*)
+    parameter type w_credit_t = logic [WCntWidth-1:0],
+    /// The type of the read credit counter (*DO NOT OVERWRITE*)
+    parameter type r_credit_t = logic [RCntWidth-1:0]
+) (
+    /// Clock
+    input  logic clk_i,
+    /// Asynchronous reset, active low
+    input  logic rst_ni,
+
+    /// AXI4+ATOP request in
+    input  axi_req_t req_i,
+    /// AXI4+ATOP response out
+    output axi_rsp_t rsp_o,
+    /// AXI4+ATOP request out
+    output axi_req_t req_o,
+    /// AXI4+ATOP response in
+    input  axi_rsp_t rsp_i,
+
+    /// Amount of write credit (number of outstanding write transfers)
+    input  w_credit_t w_credit_i,
+    /// Amount of read credit (number of outstanding read transfers)
+    input  r_credit_t r_credit_i
+);
+
+    // ax throttled valids
+    logic throttled_aw_valid;
+    logic throttled_ar_valid;
+
+    // ax throttled readies
+    logic throttled_aw_ready;
+    logic throttled_ar_ready;
+
+    // limit Aw requests -> wait for b
+    stream_throttle #(
+        .MaxNumPending ( MaxNumAwPending  )
+    ) i_stream_throttle_aw (
+        .clk_i,
+        .rst_ni,
+        .req_valid_i ( req_i.aw_valid     ),
+        .req_valid_o ( throttled_aw_valid ),
+        .req_ready_i ( rsp_i.aw_ready     ),
+        .req_ready_o ( throttled_aw_ready ),
+        .rsp_valid_i ( rsp_i.b_valid      ),
+        .rsp_ready_i ( req_i.b_ready      ),
+        .credit_i    ( w_credit_i         )
+    );
+
+    // limit Ar requests -> wait for r.last
+    stream_throttle #(
+        .MaxNumPending ( MaxNumArPending  )
+    ) i_stream_throttle_ar (
+        .clk_i,
+        .rst_ni,
+        .req_valid_i ( req_i.ar_valid               ),
+        .req_valid_o ( throttled_ar_valid           ),
+        .req_ready_i ( rsp_i.ar_ready               ),
+        .req_ready_o ( throttled_ar_ready           ),
+        .rsp_valid_i ( rsp_i.r_valid & rsp_i.r.last ),
+        .rsp_ready_i ( req_i.r_ready                ),
+        .credit_i    ( r_credit_i                   )
+    );
+
+    // connect the throttled request bus (its a through connection - except for the ax valids)
+    always_comb begin : gen_throttled_req_conn
+        req_o          = req_i;
+        req_o.aw_valid = throttled_aw_valid;
+        req_o.ar_valid = throttled_ar_valid;
+    end
+
+    // connect the throttled response bus (its a through connection - except for the ax readies)
+    always_comb begin : gen_throttled_rsp_conn
+        rsp_o          = rsp_i;
+        rsp_o.aw_ready = throttled_aw_ready;
+        rsp_o.ar_ready = throttled_ar_ready;
+    end
+
+endmodule : axi_throttle

src_files.yml

@@ -37,6 +37,7 @@ axi:
     - src/axi_modify_address.sv
     - src/axi_mux.sv
     - src/axi_serializer.sv
+    - src/axi_throttle.sv
     - src/axi_to_mem.sv
     # Level 3
     - src/axi_cdc.sv