Shmuel doc

docs/fabric/MAS_fabric/mas_fabric.md

@@ -0,0 +1,47 @@
+# Fabric MAS
+
+## 1. Overview
+
+**Brief Description:**
+This document outlines the micro-architecture of the `fabric` module, responsible for managing data routing, arbitration, and communication between different tiles in a tile-based system.
+
+**Purpose and Functionality:**
+The `fabric` module serves as the interconnection fabric, enabling communication between tiles within the system. It handles data exchange in multiple directions (North, East, West, South) and facilitates UART communication. Local tile IDs are generated based on tile positions for routing.
+
+## 2. Block Diagram
+![fabric](/drawio/fabric.jpg)
+
+## 3. Interfaces
+
+### Signal Descriptions:
+
+| Signal Name            | Direction | Description                                             |
+|------------------------|-----------|---------------------------------------------------------|
+| clk                    | Input     | Clock signal.                                           |
+| rst                    | Input     | Reset signal.                                           |
+| RstPc                  | Input     | Reset for the program counter.                          |
+| InUartValid            | Input     | Valid signal for UART read/write requests.              |
+| InUart                 | Input     | UART transaction details (read/write).                  |
+| OutUartValid           | Output    | Valid signal for UART responses.                        |
+| OutUart                | Output    | UART response details.                                  |
+
+
+## 4. Functional Description
+
+**Operational Modes:**
+The `fabric` module operates in a single mode, facilitating data routing and communication between tiles.
+
+**Data Flow Description:**
+1. The module receives clock (`clk`) and reset (`rst`) signals for control.
+2. It handles UART read/write requests through `InUartValid` and `InUart` and provides UART responses via `OutUartValid` and `OutUart`.
+3. For tile-to-tile communication, it manages data exchange in all four cardinal directions (North, East, West, South) using arrays of signals (`in_` and `out_` signals) for request validity, transaction details, and ready signals.
+4. Local tile IDs are generated based on tile positions for routing.
+
+## 5. Configuration and Control
+
+**Configuration Registers:**
+The `fabric` module does not include explicit configuration registers. Configuration and control may be implemented at a higher system level.
+
+## 6. Testing and Verification
+
+Specify details about testing and verification procedures in the verification sidebar.

docs/fabric/MAS_fabric/mas_mini_core_tile.md

@@ -0,0 +1,92 @@
+# Mini_core_tile MAS
+
+## 1. Overview
+
+**Brief Description:**
+This document outlines the micro-architecture of the `mini_core_tile` module, which serves as a tile within a tile-based system. It manages data communication with neighboring tiles in multiple directions (North, East, West, South) and includes a local interface.
+
+**Purpose and Functionality:**
+The `mini_core_tile` module facilitates inter-tile communication and routing of data within a tile-based system. It supports UART communication, interfaces with neighboring tiles, and includes a local interface for communication with the mini core.
+
+## 2. Block Diagram
+![mini_core_tile](/drawio/mini_core_tile.jpg)
+
+## 3. Interfaces
+
+## North Interface
+
+| Signal Name            | Description                              |
+|------------------------|------------------------------------------|
+| in_north_req_valid     | Validity of incoming North requests.     |
+| in_north_req           | Incoming North requests.                 |
+| in_north_ready         | Ready signal for incoming North requests.|
+| out_north_req_valid    | Validity of outgoing North requests.     |
+| out_north_req          | Outgoing North requests.                 |
+| out_north_ready        | Ready signal for outgoing North requests.|
+
+## East Interface
+
+| Signal Name            | Description                              |
+|------------------------|------------------------------------------|
+| in_east_req_valid      | Validity of incoming East requests.      |
+| in_east_req            | Incoming East requests.                  |
+| in_east_ready          | Ready signal for incoming East requests. |
+| out_east_req_valid     | Validity of outgoing East requests.      |
+| out_east_req           | Outgoing East requests.                  |
+| out_east_ready         | Ready signal for outgoing East requests. |
+
+## West Interface
+
+| Signal Name            | Description                              |
+|------------------------|------------------------------------------|
+| in_west_req_valid      | Validity of incoming West requests.      |
+| in_west_req            | Incoming West requests.                  |
+| in_west_ready          | Ready signal for incoming West requests. |
+| out_west_req_valid     | Validity of outgoing West requests.      |
+| out_west_req           | Outgoing West requests.                  |
+| out_west_ready         | Ready signal for outgoing West requests. |
+
+## South Interface
+
+| Signal Name            | Description                              |
+|------------------------|------------------------------------------|
+| in_south_req_valid     | Validity of incoming South requests.     |
+| in_south_req           | Incoming South requests.                 |
+| in_south_ready         | Ready signal for incoming South requests.|
+| out_south_req_valid    | Validity of outgoing South requests.     |
+| out_south_req          | Outgoing South requests.                 |
+| out_south_ready        | Ready signal for outgoing South requests.|
+
+## Local Interface
+
+| Signal Name            | Description                              |
+|------------------------|------------------------------------------|
+| in_local_req_valid     | Validity of incoming local requests.     |
+| in_local_req           | Incoming local requests.                 |
+| in_local_ready         | Ready signal for incoming local requests.|
+| OutFabricValidQ505H    | Validity of outgoing local requests.     |
+| OutFabricQ505H         | Outgoing local requests.                 |
+| out_local_ready        | Ready signal for outgoing local requests.|
+
+
+
+
+## 4. Functional Description
+
+**Operational Modes:**
+The `mini_core_tile` module operates in a single mode, facilitating data routing and communication with neighboring tiles.
+
+**Data Flow Description:**
+1. The module receives clock (`clk`) and reset (`rst`) signals for control.
+2. It manages data communication in all four cardinal directions (North, East, West, South) with neighboring tiles using the specified input and output signals.
+3. Local requests are received and processed via the `in_local_req_valid`, `in_local_req`, and `in_local_ready` signals.
+4. It interfaces with the `router` module for routing data between directions.
+
+## 5. Configuration and Control
+
+**Configuration Registers:**
+The `mini_core_tile` module does not include explicit configuration registers. Configuration and control may be implemented at a higher system level.
+
+## 6. Testing and Verification
+
+Specify details about testing and verification procedures in the verification sidebar.

docs/fabric/MAS_router/mas_arbiter.md

@@ -1,4 +1,4 @@
-Micro-Architecture Specification (MAS) for Arbiter Module
+# Arbiter MAS
 # 1. Overview
 Brief Description:
 This document details the micro-architecture of an Arbiter module designed to manage multiple client requests and select a winner based on a predefined arbitration scheme.
@@ -7,8 +7,7 @@ Purpose and Functionality:
 The Arbiter module is used to arbitrate among NUM_CLIENTS clients. It determines which client gains access based on the input signals.
 
 # 2. Block Diagram
-[Placeholder for Block Diagram]
-Insert High-Level Block Diagram of the Arbiter here
+![arbiter](/drawio/arbiter.jpg)
 
 # 3. Interfaces
 Signal Descriptions:
@@ -41,21 +40,6 @@ Latency:
 Typically one clock cycle for arbitration decision.
 
 # 7. Error Handling and Exceptions
-The module does not explicitly include error handling mechanisms in the provided RTL. Design-specific error handling should be considered.
+The module does not explicitly include error handling mechanisms in this design.
 # 8. Testing and Verification
-Test Plan Overview:
-
-Verify correct arbitration among multiple clients.
-Test for edge cases where multiple clients request access simultaneously.
-Verification Strategies:
-
-Simulate with varying numbers of clients.
-Stress test with simultaneous requests.
-
-# 9. Change Log
-Revision History:
-
-Initial version: [Date]
-Author Information:
-
-[Author Name]
+In the verification sidebar.

docs/fabric/MAS_router/mas_fifo.md

@@ -1,3 +1,4 @@
+# FIFO MAS
 # Overview
 Brief Description:
 This document describes the micro-architecture specification of a FIFO (First-In-First-Out) module, designed to temporarily store and manage data in a sequential manner.

docs/fabric/MAS_router/mas_fifo_arb.md

@@ -1,27 +1,57 @@
-# Fifo_Arb - MAS
-The fifo_arb Micro-Architecture-Specification   
-A FIFO (First-In-First-Out) arbiter is a component that arbitrates between multiple FIFOs.
-
-
-## General-Description
-- Round Robin arbiter between 4 FIFOs
-- Using the Ready signals from the target TILE to determine which FIFO to pop from
-
-
-## Block Diagram
-
-
-## Top level interface
-
-
-## Main components:
-
-### fifo
-- parametrize FIFO (first in-first out) 
-#### Motivation:
-- storage requests without losing anyone.  
-
-### arbiter
-- Round Robin arbiter
-#### Motivation:
-- controll the output So that all the information is out. 
+# FIFO_arb MAS
+# 1. Overview
+Brief Description:
+This document outlines the micro-architecture of a fifo_arb module designed to manage multiple client requests and select a winner based on a predefined arbitration scheme. It interfaces with multiple fifos, arbitrates among them, and selects a winner to transmit data to the next tile.
+
+Purpose and Functionality:
+The fifo_arb module arbitrates among NUM_CLIENTS clients connected to different fifos. It uses an arbiter module to determine a winner based on the availability of data in the fifos and the readiness of the next tile to accept data.
+
+# 2. Block Diagram
+![fifo_arb](/drawio/fifo_arb.jpg)
+
+# 3. Interfaces
+Signal Descriptions:
+
+| Signal Name                   | Direction | Description                                                        |
+|-------------------------------|-----------|--------------------------------------------------------------------|
+| clk                           | Input     | Clock signal.                                                      |
+| rst                           | Input     | Reset signal.                                                      |
+| valid_alloc_req0, 1, 2, 3      | Input     | Signals indicating valid allocation requests from different clients (0 to NUM_CLIENTS-1). |
+| alloc_req0, 1, 2, 3            | Input     | Transaction details of allocation requests from different clients (0 to NUM_CLIENTS-1). |
+| out_ready_fifo0, 1, 2, 3       | Output    | Signals indicating whether the corresponding fifo (0 to NUM_CLIENTS-1) is ready to accept data. |
+| winner_req                    | Output    | Transaction details of the winning request to be sent to the next tile. |
+| winner_req_valid              | Output    | Signal indicating the validity of the winning request.              |
+| in_ready_north_arb_fifo       | Input     | Signal indicating the readiness of the arbiter fifo in the North direction. |
+| in_ready_east_arb_fifo        | Input     | Signal indicating the readiness of the arbiter fifo in the East direction.  |
+| in_ready_south_arb_fifo       | Input     | Signal indicating the readiness of the arbiter fifo in the South direction. |
+| in_ready_west_arb_fifo        | Input     | Signal indicating the readiness of the arbiter fifo in the West direction.  |
+| in_ready_local_arb_fifo       | Input     | Signal indicating the readiness of the arbiter fifo in the Local direction. |
+
+# 4. Functional Description
+Operational Modes:
+
+The module arbitrates among NUM_CLIENTS clients connected to different fifos.
+It uses the arbiter module to determine a winner based on fifo and next tile readiness.
+Data Flow Description:
+
+Allocation requests from different clients are prioritized based on fifo and next tile readiness.
+Upon determining a winner, the winning request is sent to the next tile.
+
+# 5. Configuration and Control
+Configuration Registers:
+
+NUM_CLIENTS: Defines the number of clients participating in arbitration.  
+FIFO_ARB_FIFO_DEPTH: Defines the depth of each fifo in the fifo_arb module.
+
+# 6. Performance and Characteristics
+Throughput:
+Dependent on the clock frequency.
+
+Latency:
+Dependent on the arbitration scheme and fifo availability.
+
+# 7. Error Handling and Exceptions
+The module does not explicitly include error handling mechanisms in this design.
+
+# 8. Testing and Verification
+In the verification sidebar.

docs/fabric/MAS_router/mas_next_tile_fifo_arb.md

@@ -1,2 +1,51 @@
-# next_tile_fifo_arb - MAS
-Micro Architecture specification for the next_tile_fifo_arb component
+# Next_tile_fifo_arb MAS
+# 1. Overview
+Brief Description:
+This document outlines the micro-architecture of the next_tile_fifo_arb module, which is designed to determine the cardinal direction for forwarding requests from the current tile to the next tile in a tile-based system. It takes into account the current tile's ID and the target address to make this decision.
+
+Purpose and Functionality:
+The next_tile_fifo_arb module is responsible for selecting the cardinal direction (NORTH, EAST, SOUTH, WEST, or LOCAL) for forwarding requests based on the current tile's ID, the target address, and the availability of requests from different directions.
+
+
+# 2. Interfaces
+Signal Descriptions:
+
+| Signal Name                           | Direction | Description                                              |
+|---------------------------------------|-----------|----------------------------------------------------------|
+| clk                                   | Input     | Clock signal.                                            |
+| local_tile_id                         | Input     | The ID of the current tile.                              |
+| in_north_req_valid                    | Input     | Signal indicating the validity of requests from the North direction. |
+| in_east_req_valid                     | Input     | Signal indicating the validity of requests from the East direction.  |
+| in_south_req_valid                    | Input     | Signal indicating the validity of requests from the South direction. |
+| in_west_req_valid                     | Input     | Signal indicating the validity of requests from the West direction.  |
+| in_local_req_valid                    | Input     | Signal indicating the validity of requests from the Local direction. |
+| in_north_req_address [31:24]          | Input     | Address information associated with requests from the North direction. |
+| in_east_req_address [31:24]           | Input     | Address information associated with requests from the East direction.  |
+| in_south_req_address [31:24]          | Input     | Address information associated with requests from the South direction. |
+| in_west_req_address [31:24]           | Input     | Address information associated with requests from the West direction.  |
+| in_local_req_address [31:24]          | Input     | Address information associated with requests from the Local direction. |
+| in_north_next_tile_fifo_arb_card      | Output    | The selected cardinal direction for forwarding requests from the North direction. |
+| in_south_next_tile_fifo_arb_card      | Output    | The selected cardinal direction for forwarding requests from the South direction. |
+| in_east_next_tile_fifo_arb_card       | Output    | The selected cardinal direction for forwarding requests from the East direction.  |
+| in_west_next_tile_fifo_arb_card       | Output    | The selected cardinal direction for forwarding requests from the West direction.  |
+| in_local_next_tile_fifo_arb_card      | Output    | The selected cardinal direction for forwarding requests from the Local direction. |
+
+# 3. Functional Description
+Operational Modes:
+
+The module calculates the appropriate cardinal direction for forwarding requests based on the current tile's ID, the target address, and the availability of requests from different directions.
+
+Data Flow Description:
+
+1. The module receives requests from various directions, each with its associated validity signal and address.
+2. It calculates the next_tile_id based on the current tile's ID and the predefined NEXT_TILE_CARDINAL parameter.
+3. It determines the priority of different cardinal directions based on the target address and the current tile's ID.
+4. The selected cardinal direction for each request is then provided as output.
+
+# 4. Configuration and Control
+Configuration Registers:
+
+The module is primarily configured through the `NEXT_TILE_CARDINAL` parameter, which specifies the preferred cardinal direction for forwarding requests.
+
+# 5. Testing and Verification
+In the verification sidebar.