# samip08/asynchronous-fifo-based-axitoapb-bridge architecture

> Architecture diagram of the GitHub repository samip08/asynchronous-fifo-based-axitoapb-bridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samip08/asynchronous-fifo-based-axitoapb-bridge
- Repository: https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge

## Overview

1. **What this repo implements**
   This is a Verilog RTL design for an **AXI-to-APB bridge**. The bridge accepts AXI-style read/write transactions on one side, converts them into APB master cycles on the other side, and returns responses back to AXI. The design is organized as a set of small FSM-based blocks with clock-domain-crossing FIFOs in the middle.

2. **Top-level composition**
   `RTL/Top_module.v` is the integration point. It ties together:
   - `axi_slave_fsm.v` for AXI-side transaction capture and response handling
   - `async_fifo_core.v` for CDC-safe buffering
   - `apb_master_fsm.v` for APB bus sequencing
   - `apb_slave_mux.v` for selecting one of many APB slaves
   This is the main architectural boundary: AXI ingress, buffering/CDC, APB egress.

3. **AXI-side request handling**
   `axi_slave_fsm.v` acts like a protocol adapter on the AXI side. It latches address/data when valid signals arrive, tolerates cases where address and data do not arrive in the same cycle, and keeps the AXI master stalled until the bridge is ready. It has separate handling for write and read requests, with state transitions designed to avoid overwriting latched values.

4. **Two-way buffering across domains**
   `async_fifo_core.v` is the key CDC mechanism. The README indicates gray-coded read/write pointers, binary local pointers, and use of “next” pointer values to make empty/full decisions at the correct cycle. This prevents classic CDC failures like overwriting unread data or reading unpublished data. The design also uses asynchronous reset behavior and separate FIFO usage for request and response traffic.

5. **Transaction flow for writes**
   For writes, the AXI-side FSM captures write address/data, pushes the request into the write-side FIFO, and asserts AXI ready/valid-style completion signals only when safe. The APB side later consumes the request, drives the APB bus, and returns a write response. The bridge also handles error cases by returning an APB/AXI error response rather than blindly completing the transfer.

6. **Transaction flow for reads**
   For reads, the AXI-side FSM captures the read address and sends a read request through the FIFO. The APB master then performs the APB access, collects `prdata`, and sends the result back through the response path. The AXI-side FSM waits until the response FIFO produces data before completing the read.

7. **APB master sequencing**
   `apb_master_fsm.v` is the protocol engine for APB. It drives the APB phases (`psel`, `penable`, `pready` handling) and distinguishes read versus write behavior. The README shows an intentional cycle delay to avoid consuming stale FIFO values and to let request/response handshakes settle cleanly before the state machine commits to the transaction type.

8. **Error propagation and recovery**
   Error handling is built into the bridge path, not treated as an afterthought. The APB master can enter an error/response path when a peripheral signals failure, and the AXI side also detects local decode errors such as an invalid address region (`address[31:28] == 4'h2` in the README). On error, the design clears outgoing flags and returns to idle cleanly.

9. **APB slave selection**
   `apb_slave_mux.v` provides a 16-way APB slave fanout. The selected slave is determined by 4 address bits, and the mux forwards the chosen slave’s `prdata`, `pready`, and error signals back to the APB master. Only the addressed slave is effectively active, while the others remain deasserted.

10. **Clocking and reset boundaries**
    The design explicitly treats the AXI and APB sides as decoupled domains, with the FIFO forming the safe boundary. The README also notes asynchronous reset usage, especially to avoid spurious behavior at power-up. This means the architecture is not just a simple bus adapter; it is a CDC-aware bridge.

11. **Verification structure**
    The `TB/` directory mirrors the RTL structure: there are testbenches for the top module, AXI slave FSM, APB master FSM, APB slave mux, async FIFO, and the overall AXI-bridge path. This suggests a modular verification strategy where each subsystem can be validated independently before end-to-end integration.

12. **Supporting docs and artifacts**
    `Waveforms/` contains waveform images that document key design issues and fixes, especially around FIFO pointer correctness and bridge sequencing. `Extra_utilities/` includes reference material and a `rom_memory.v` helper, likely used for stimulus or memory modeling in verification.

13. **How to draw the architecture**
    The clearest diagram is a left-to-right pipeline:
    **AXI master → AXI slave FSM → async FIFO(s) → APB master FSM → APB slave mux → APB peripherals**, with the read response returning along the reverse path. The important architectural boundaries are the AXI/APB protocol boundary, the CDC FIFO boundary, and the APB slave-selection boundary.

Main entry points: [`RTL/axi_slave_fsm.v`](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/axi_slave_fsm.v) (AXI FSM), [`RTL/apb_master_fsm.v`](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/apb_master_fsm.v) (APB FSM), [`RTL/async_fifo_core.v`](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/async_fifo_core.v) (Req FIFO), [`RTL/Top_module.v`](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/Top_module.v) (Top module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rtl["RTL"]
  node_top_module["Top module<br/>bridge top<br/>[Top_module.v]"]
  node_axi_slave_fsm["AXI FSM<br/>AXI adapter<br/>[axi_slave_fsm.v]"]
  node_req_fifo["Req FIFO<br/>CDC buffer<br/>[async_fifo_core.v]"]
  node_resp_fifo["Resp FIFO<br/>CDC buffer<br/>[async_fifo_core.v]"]
  node_apb_master_fsm["APB FSM<br/>APB master<br/>[apb_master_fsm.v]"]
  node_apb_slave_mux["APB mux<br/>slave select<br/>[apb_slave_mux.v]"]
  node_axi_addr_check{{"Addr check<br/>decode guard<br/>[axi_slave_fsm.v]"}}
end

subgraph group_tb["TB"]
  node_top_tb["Top TB<br/>integration testbench<br/>[Top_module_tb.v]"]
  node_axi_bridge_tb["Bridge TB<br/>system testbench<br/>[axi_bridge_tb.v]"]
  node_module_tbs["Module TBs<br/>unit testbenches"]
end

subgraph group_docs["Docs"]
  node_waveforms["Waveforms<br/>debug artifacts"]
  node_refs["References<br/>notes"]
end

node_axi_master(("AXI master<br/>external bus master"))
node_apb_slaves(("APB slaves<br/>peripherals"))
node_write_flow(("Write path<br/>transaction flow"))
node_read_flow(("Read path<br/>transaction flow"))
node_bridge_reset(("Reset boundary<br/>async reset"))

node_axi_master -->|"AXI requests"| node_axi_slave_fsm
node_axi_slave_fsm -->|"enqueue req"| node_req_fifo
node_req_fifo -->|"dequeue req"| node_apb_master_fsm
node_apb_master_fsm -->|"APB access"| node_apb_slave_mux
node_apb_slave_mux -->|"select slave"| node_apb_slaves
node_apb_slaves -->|"prdata/pready/pslverr"| node_apb_slave_mux
node_apb_master_fsm -->|"enqueue resp"| node_resp_fifo
node_resp_fifo -->|"dequeue resp"| node_axi_slave_fsm
node_axi_slave_fsm -->|"decode guard"| node_axi_addr_check
node_axi_addr_check -->|"error resp"| node_resp_fifo
node_axi_slave_fsm -->|"write control"| node_write_flow
node_axi_slave_fsm -->|"read control"| node_read_flow
node_write_flow -->|"write req"| node_req_fifo
node_read_flow -->|"read req"| node_req_fifo
node_apb_master_fsm -->|"write resp"| node_write_flow
node_apb_master_fsm -->|"read resp"| node_read_flow
node_top_module -->|"instantiates"| node_axi_slave_fsm
node_top_module -->|"instantiates"| node_req_fifo
node_top_module -->|"instantiates"| node_resp_fifo
node_top_module -->|"instantiates"| node_apb_master_fsm
node_top_module -->|"instantiates"| node_apb_slave_mux
node_bridge_reset -.->|"reset"| node_axi_slave_fsm
node_bridge_reset -.->|"reset"| node_req_fifo
node_bridge_reset -.->|"reset"| node_resp_fifo
node_bridge_reset -.->|"reset"| node_apb_master_fsm
node_top_tb -->|"verifies"| node_top_module
node_axi_bridge_tb -->|"verifies"| node_write_flow
node_axi_bridge_tb -->|"verifies"| node_read_flow
node_module_tbs -->|"verifies"| node_axi_slave_fsm
node_module_tbs -->|"verifies"| node_apb_master_fsm
node_module_tbs -->|"verifies"| node_req_fifo
node_module_tbs -->|"verifies"| node_apb_slave_mux
node_waveforms -.->|"documents"| node_req_fifo
node_refs -.->|"supports"| node_module_tbs

click node_top_module "https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/Top_module.v"
click node_axi_slave_fsm "https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/axi_slave_fsm.v"
click node_req_fifo "https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/async_fifo_core.v"
click node_resp_fifo "https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/async_fifo_core.v"
click node_apb_master_fsm "https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/apb_master_fsm.v"
click node_apb_slave_mux "https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/apb_slave_mux.v"
click node_axi_addr_check "https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/axi_slave_fsm.v"
click node_top_tb "https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/TB/Top_module_tb.v"
click node_axi_bridge_tb "https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/TB/axi_bridge_tb.v"
click node_waveforms "https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/tree/main/Waveforms"
click node_refs "https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/tree/main/Extra_utilities"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_top_module,node_axi_slave_fsm,node_req_fifo,node_resp_fifo,node_apb_master_fsm,node_apb_slave_mux,node_axi_addr_check toneBlue
class node_top_tb,node_axi_bridge_tb,node_module_tbs toneAmber
class node_waveforms,node_refs toneMint
class node_axi_master,node_apb_slaves,node_write_flow,node_read_flow,node_bridge_reset toneNeutral
```

## Components

### RTL

Synthesisable bridge logic

- [Top module](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/Top_module.v): bridge top · Integrates AXI capture, CDC buffering, APB sequencing, and slave selection · `RTL/Top_module.v`
- [AXI FSM](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/axi_slave_fsm.v): AXI adapter · Captures AXI requests, holds ready/valid handshakes, and returns read or write responses · `RTL/axi_slave_fsm.v`
- [Req FIFO](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/async_fifo_core.v): CDC buffer · Asynchronous FIFO used to carry requests across the clock boundary · `RTL/async_fifo_core.v`
- [Resp FIFO](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/async_fifo_core.v): CDC buffer · Asynchronous FIFO used to return APB results and responses back to the AXI side · `RTL/async_fifo_core.v`
- [APB FSM](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/apb_master_fsm.v): APB master · Drives APB setup and access phases and formats read or write outcomes · `RTL/apb_master_fsm.v`
- [APB mux](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/apb_slave_mux.v): slave select · Selects one of 16 APB slaves using address bits and forwards return signals · `RTL/apb_slave_mux.v`
- [Addr check](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/RTL/axi_slave_fsm.v): decode guard · Local address-region check used to flag invalid or unsupported transactions · `RTL/axi_slave_fsm.v`

### TB

Module-level and end-to-end verification

- [Top TB](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/TB/Top_module_tb.v): integration testbench · End-to-end testbench for the bridge top module · `TB/Top_module_tb.v`
- [Bridge TB](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/blob/main/TB/axi_bridge_tb.v): system testbench · Verification of the overall AXI-to-APB bridge behavior · `TB/axi_bridge_tb.v`
- **Module TBs**: unit testbenches · Focused benches for AXI FSM, APB FSM, async FIFO, and APB mux

### Docs

Reference material and waveform artifacts

- [Waveforms](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/tree/main/Waveforms): debug artifacts · Captured traces documenting FIFO pointer and sequencing behavior · `Waveforms`
- [References](https://github.com/samip08/asynchronous-fifo-based-axitoapb-bridge/tree/main/Extra_utilities): notes · Supporting reading material and utility references for design and verification · `Extra_utilities`

### Other components

- **AXI master**: external bus master · Source of AXI read and write transactions
- **APB slaves**: peripherals · Target APB peripherals behind the address-decoding mux
- **Write path**: transaction flow · Captures write address and data, forwards the request, and returns a write response
- **Read path**: transaction flow · Captures read address, forwards the request, and waits for returned data
- **Reset boundary**: async reset · Asynchronous reset behavior used to keep CDC and protocol state clean at startup

## Connections

- AXI master → AXI FSM: AXI requests · Master issues read and write transactions into the bridge
- AXI FSM → Req FIFO: enqueue req · Captured requests are pushed toward the CDC boundary
- Req FIFO → APB FSM: dequeue req · APB side consumes requests after crossing clock domains
- APB FSM → APB mux: APB access · Master engine drives the selected APB transfer
- APB mux → APB slaves: select slave · Address bits choose one of the APB targets
- APB slaves → APB mux: prdata/pready/pslverr · Selected peripheral returns read data, ready, and error status
- APB FSM → Resp FIFO: enqueue resp · Completed APB result is buffered for return to AXI
- Resp FIFO → AXI FSM: dequeue resp · AXI side completes the original transaction after response arrival
- AXI FSM → Addr check: decode guard · Address region checks can short-circuit unsupported requests
- Addr check → Resp FIFO: error resp · Invalid addresses are converted into an error response path
- AXI FSM → Write path: write control · Write-side capture and completion logic
- AXI FSM → Read path: read control · Read-side capture and completion logic
- Write path → Req FIFO: write req · Write transactions are packaged and sent to the APB side
- Read path → Req FIFO: read req · Read transactions are packaged and sent to the APB side
- APB FSM → Write path: write resp · Write completion or failure is returned upstream
- APB FSM → Read path: read resp · Read data or failure is returned upstream
- Top module → AXI FSM: instantiates · Top-level integration includes the AXI-side FSM
- Top module → Req FIFO: instantiates · Top-level integration includes request buffering
- Top module → Resp FIFO: instantiates · Top-level integration includes response buffering
- Top module → APB FSM: instantiates · Top-level integration includes the APB master FSM
- Top module → APB mux: instantiates · Top-level integration includes APB slave selection
- Reset boundary → AXI FSM: reset · Async reset clears AXI-side state
- Reset boundary → Req FIFO: reset · Async reset clears FIFO pointers and flags
- Reset boundary → Resp FIFO: reset · Async reset clears FIFO pointers and flags
- Reset boundary → APB FSM: reset · Async reset clears APB-side state
- Top TB → Top module: verifies · Integration testbench exercises the full top module
- Bridge TB → Write path: verifies · System bench covers write-path behavior
- Bridge TB → Read path: verifies · System bench covers read-path behavior
- Module TBs → AXI FSM: verifies · Module benches isolate the AXI FSM
- Module TBs → APB FSM: verifies · Module benches isolate the APB master FSM
- Module TBs → Req FIFO: verifies · Module benches isolate FIFO correctness
- Module TBs → APB mux: verifies · Module benches isolate the APB slave mux
- Waveforms → Req FIFO: documents · Waveforms capture FIFO pointer and boundary behavior
- References → Module TBs: supports · Reference material and utilities support verification work