# jonathanjing/asynchronous-fifo architecture

> Architecture diagram of the GitHub repository jonathanjing/asynchronous-fifo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jonathanjing/asynchronous-fifo
- Repository: https://github.com/jonathanjing/asynchronous-fifo

## Overview

##### Project type and purpose
- This is a hardware design project written in Verilog for implementing and optimizing both synchronous and asynchronous FIFOs (First-In-First-Out queues).
- The README makes clear the focus is on clock-domain crossing, metastability safety via Gray-coded pointers, and FIFO depth/width conversion.

##### File structure
- Top-level Verilog modules:
- asy_fifo.v – asynchronous FIFO implementation
- Syn_FIFO.v – synchronous FIFO implementation (for comparison/benchmark)
- Gray-code utilities (under Gray_code/):
- Binary_2_gray.v, Gray_2_binary.v – pointer Gray-encoding and decoding
- Gray code.md – background on Gray code use for metastability mitigation
- Documentation:
- README.md – project overview, theory, references
- New function.md – notes on additional features (e.g. width conversion)

##### Key architectural insights from the README
- FIFO consists of separate write and read pointer controllers, a dual‐port memory array, and control logic generating full/empty flags.
- Asynchronous design requires two‐stage synchronizers for cross‐domain pointer sampling and Gray‐code conversion to avoid multiple‐bit flips.
- Supports optional data‐width conversion (e.g. 32-bit write into 16-bit read).

##### Main components
a. Write‐domain block (clock A)
- Write pointer (binary + Gray encoder)
- Write data input interface
- Write‐side full‐flag logic
- Synchronizer to receive read pointer from read domain
b. Read‐domain block (clock B)
- Read pointer (binary + Gray encoder)
- Read data output interface
- Read‐side empty‐flag logic
- Synchronizer to receive write pointer from write domain
c. Dual‐port memory array
- One port clocked by write clock, one by read clock
- Data‐width conversion logic (optional)
d. Cross‐domain synchronizers
- Gray-coded pointer signals passed through two‐stage flip-flop synchronizers

##### Relationships and interactions
- Data flows from the write‐domain interface → memory → read‐domain interface.
- Each domain’s pointer controller drives one memory port.
- Full flag: write pointer compares (after synchronizer) to read pointer Gray code.
- Empty flag: read pointer compares (after synchronizer) to write pointer Gray code.

##### Architectural patterns & design principles
- Clock-domain crossing using two-stage synchronizers.
- Gray-code encoding of pointers to ensure single-bit transitions.
- Separation of control logic from data storage (clean RTL modularity).
- Optional width conversion stage decoupled from pointer/control logic.

##### Technologies/frameworks/libraries
- Pure Verilog (no external IP).
- Use of simple two‐flip‐flop synchronizer primitives.
- Dual-port RAM can be inferred or mapped to FPGA block RAM.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Write Clock Domain
    subgraph "Write Clock Domain"
        direction TB
        WP["Write Pointer Controller"]:::write
        ENC["Binary-to-Gray Encoder"]:::write
        WDI["Write Data Input Interface"]:::write
        WFF["Full-Flag Logic"]:::write
        RSYNC["ReadPtr Synchronizer"]:::write
    end

    %% Shared Dual-Port Memory
    subgraph "Shared Resources"
        direction TB
        MEM["Dual-Port RAM"]:::shared
        WC["Optional Width Converter"]:::shared
    end

    %% Read Clock Domain
    subgraph "Read Clock Domain"
        direction TB
        RP["Read Pointer Controller"]:::read
        DEC["Gray-to-Binary Decoder"]:::read
        RDO["Read Data Output Interface"]:::read
        REF["Empty-Flag Logic"]:::read
        WSYNC["WritePtr Synchronizer"]:::read
    end

    %% Synchronous FIFO Benchmark
    SF["Synchronous FIFO"]:::benchmark

    %% Documentation
    MD1["Gray-code Background Notes"]:::doc
    MD2["New Function Notes"]:::doc
    MD3["Project README"]:::doc

    %% Data Flow
    WDI -->|"write data"| MEM
    MEM -->|"read data"| RDO

    %% Pointer Control
    WP --> ENC
    ENC -->|"gray code"| WSYNC
    WSYNC -->|"synchronized writeptr_gray"| RP
    RP --> DEC
    DEC -->|"binary ptr"| RP
    RP --> WSYNC
    RP --> REF
    RSYNC --> WFF
    RP -->|"gray code"| RSYNC
    RSYNC -->|"synchronized readptr_gray"| WP
    WP --> WFF

    %% Shared Memory Interface
    WP -->|"write addr"| MEM
    RP -->|"read addr"| MEM
    WC --> MEM

    %% Benchmark Link
    SF

    %% Documentation Links
    MD3

    %% Click Events
    click WP "https://github.com/jonathanjing/asynchronous-fifo/blob/master/asy_fifo.v"
    click SF "https://github.com/jonathanjing/asynchronous-fifo/blob/master/Syn_FIFO.v"
    click ENC "https://github.com/jonathanjing/asynchronous-fifo/blob/master/Gray_code/Binary_2_gray.v"
    click DEC "https://github.com/jonathanjing/asynchronous-fifo/blob/master/Gray_code/Gray_2_binary.v"
    click MD1 "https://github.com/jonathanjing/asynchronous-fifo/blob/master/Gray_code/Gray code.md"
    click MD2 "https://github.com/jonathanjing/asynchronous-fifo/blob/master/New function.md"
    click MD3 "https://github.com/jonathanjing/asynchronous-fifo/blob/master/README.md"

    %% Styling
    classDef write fill:#e3f9e5,stroke:#2ecc71,stroke-width:2px;
    classDef read fill:#e6f0fa,stroke:#3498db,stroke-width:2px;
    classDef shared fill:#f0f0f0,stroke:#95a5a6,stroke-width:2px;
    classDef benchmark fill:#fdebd0,stroke:#f39c12,stroke-width:2px;
    classDef doc fill:#f9f0f5,stroke:#8e44ad,stroke-width:2px;
    class WP,ENC,WDI,WFF,RSYNC write
    class RP,DEC,RDO,REF,WSYNC read
    class MEM,WC shared
    class SF benchmark
    class MD1,MD2,MD3 doc
```
