# guoruixin123/memoryproject architecture

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

- Interactive diagram: https://gitdiagram.com/guoruixin123/memoryproject
- Repository: https://github.com/guoruixin123/memoryproject

## Overview

1. **Repository purpose**
   - This is a **single-process C simulator** for NAND Flash and an FTL layer, aimed at teaching UFS/SSD storage internals.
   - It is not a service or library with external integrations; the whole system runs as a **command-line executable**.

2. **Top-level architecture**
   - The code is split into three functional layers:
     - `main.c`: scripted demonstration / scenario runner
     - `ftl.c`: Flash Translation Layer logic
     - `nand.c` + `nand.h`: NAND physical model and data structures
   - The architecture is intentionally layered so that **host-like requests flow downward** from `main` into `FTL`, then into `NAND`.

3. **Primary data flow**
   - A write starts as a logical request in `main.c`.
   - `ftl.c` converts the logical block address into a physical location using an **L2P mapping table**.
   - `nand.c` performs the actual simulated page program / read / block erase on the modeled hardware hierarchy.
   - On success, the FTL updates metadata such as mapping and wear state; on failure, it may mark blocks bad or skip them.

4. **Hardware model boundary**
   - `nand.h` defines the simulated device geometry and metadata layout:
     - 1 chip
     - 2 dies
     - 2 planes per die
     - 4 blocks per plane
     - 8 pages per block
     - 16-byte OOB per page
   - This boundary represents the **physical NAND layer**: it knows nothing about logical addresses or host semantics.

5. **NAND physical layer responsibilities**
   - `nand.c` models the hardware constraints:
     - read/write at **page granularity**
     - erase at **block granularity**
     - no overwrite unless the block has been erased
     - wear-out / bad-block behavior
   - It also manages page contents, OOB metadata, erase counts, and status checks for invalid operations.

6. **FTL responsibilities**
   - `ftl.c` is the software abstraction layer that makes NAND look block-addressable to a host.
   - It implements:
     - **L2P mapping**
     - **out-of-place writes**
     - **bad block management**
     - **dynamic wear leveling**
     - page allocation / free-page search
   - This is the main architectural boundary that turns raw NAND restrictions into a usable storage interface.

7. **Metadata placement**
   - The simulator uses the page **OOB region** as the place for NAND metadata such as:
     - bad block marker
     - logical mapping information
     - ECC/status fields
     - erase count
   - This mirrors real flash architecture where metadata is stored alongside page data rather than in a separate side database.

8. **State model**
   - The simulation keeps state in in-memory structs for the whole hierarchy: chip → die → plane → block → page.
   - Each page likely tracks data and OOB separately, while each block tracks erase state and lifetime.
   - This makes the simulator deterministic and easy to inspect through debug prints.

9. **Demo / scenario runner**
   - `main.c` is not business logic; it orchestrates **10 learning scenarios** and prints traces.
   - Its role is to show:
     - initialization
     - reads/writes/erases
     - logical-to-physical remapping
     - wear leveling effects
     - bad block behavior
   - The output is part of the teaching model and is used to visualize state transitions.

10. **Build and execution tooling**
   - The repo is built with plain **C99 + GCC**, using either direct compiler commands or the provided `Makefile`.
   - There are no runtime dependencies beyond the standard C toolchain.
   - The included `nand_sim.exe` is a prebuilt Windows artifact; the authoritative source is the C code itself.

11. **Observability and debugging**
   - The project uses verbose tagged logs such as `[NAND]`, `[FTL]`, and `[MAIN]` to separate concerns.
   - `nand.h` exposes debug toggles, and helper print functions allow inspection of:
     - per-block state
     - full L2P mapping
     - wear / bad-block conditions
   - This logging is central to understanding the architecture because the simulation is intended to be traced step by step.

12. **Key architectural takeaway**
   - The repo models the classic SSD stack:
     - **host-facing logical view** in `main.c`
     - **translation and policy** in `ftl.c`
     - **physical NAND constraints** in `nand.c`
   - The main diagram to draw is a strict downward flow from logical requests to physical page/block operations, with metadata and wear management feeding back upward through the FTL state.

Main entry points: [`nand.c`](https://github.com/guoruixin123/memoryproject/blob/master/nand.c) (NAND Core), [`ftl.c`](https://github.com/guoruixin123/memoryproject/blob/master/ftl.c) (FTL), [`main.c`](https://github.com/guoruixin123/memoryproject/blob/master/main.c) (Main), [`nand.h`](https://github.com/guoruixin123/memoryproject/blob/master/nand.h) (NAND Layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI Demo"]
  node_main_c["Main<br/>scenario runner<br/>[main.c]"]
  node_trace_logs["Logs<br/>debug trace"]
end

subgraph group_ftl["FTL Layer"]
  node_ftl_c["FTL<br/>translation layer<br/>[ftl.c]"]
  node_l2p_map["L2P Map<br/>mapping table"]
  node_alloc_policy{{"Alloc Policy<br/>wear leveling"}}
  node_bad_block_mgmt{{"Bad Blocks<br/>failure policy"}}
end

subgraph group_nand["NAND Model"]
  node_nand_c["NAND Core<br/>physical model<br/>[nand.c]"]
  node_nand_h["NAND Layout<br/>geometry defs<br/>[nand.h]"]
  node_geom[("Geometry<br/>device model")]
  node_page_ops(("Page Ops<br/>granular I/O"))
  node_erase_ops{{"Erase Ops<br/>block control"}}
  node_oob_meta["OOB Meta<br/>metadata store"]
  node_wear_state[("Wear State<br/>lifetime state")]
end

subgraph group_tooling["Tooling"]
  node_makefile["Build<br/>toolchain"]
  node_readme["Docs<br/>guide<br/>[README.md]"]
  node_tutorial["Tutorial<br/>guide<br/>[TUTORIAL.md]"]
end

node_main_c -->|"logical requests"| node_ftl_c
node_ftl_c -->|"physical ops"| node_nand_c
node_ftl_c -->|"updates"| node_l2p_map
node_ftl_c -->|"allocates"| node_alloc_policy
node_ftl_c -->|"handles"| node_bad_block_mgmt
node_nand_c -->|"uses layout"| node_nand_h
node_nand_h -->|"defines"| node_geom
node_nand_c -->|"implements"| node_page_ops
node_nand_c -->|"implements"| node_erase_ops
node_nand_c -->|"stores"| node_oob_meta
node_nand_c -->|"tracks"| node_wear_state
node_main_c -->|"prints"| node_trace_logs
node_ftl_c -->|"reports"| node_trace_logs
node_nand_c -->|"reports"| node_trace_logs
node_makefile -->|"builds"| node_main_c
node_readme -.->|"explains"| node_tutorial

click node_main_c "https://github.com/guoruixin123/memoryproject/blob/master/main.c"
click node_ftl_c "https://github.com/guoruixin123/memoryproject/blob/master/ftl.c"
click node_nand_c "https://github.com/guoruixin123/memoryproject/blob/master/nand.c"
click node_nand_h "https://github.com/guoruixin123/memoryproject/blob/master/nand.h"
click node_makefile "https://github.com/guoruixin123/memoryproject/tree/master/Makefile"
click node_readme "https://github.com/guoruixin123/memoryproject/blob/master/README.md"
click node_tutorial "https://github.com/guoruixin123/memoryproject/blob/master/TUTORIAL.md"

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_main_c,node_trace_logs toneBlue
class node_ftl_c,node_l2p_map,node_alloc_policy,node_bad_block_mgmt toneAmber
class node_nand_c,node_nand_h,node_geom,node_page_ops,node_erase_ops,node_oob_meta,node_wear_state toneMint
class node_makefile,node_readme,node_tutorial toneRose
```

## Components

### CLI Demo

Scripted scenarios and top-level execution

- [Main](https://github.com/guoruixin123/memoryproject/blob/master/main.c): scenario runner · Runs the command-line teaching scenarios and drives simulated requests. · `main.c`
- **Logs**: debug trace · Tagged output used to explain state transitions step by step.

### FTL Layer

Logical-to-physical translation and policy

- [FTL](https://github.com/guoruixin123/memoryproject/blob/master/ftl.c): translation layer · Converts logical requests into physical NAND operations. · `ftl.c`
- **L2P Map**: mapping table · Tracks logical block to physical page placement.
- **Alloc Policy**: wear leveling · Chooses free pages, performs out-of-place writes, and spreads wear.
- **Bad Blocks**: failure policy · Skips or marks failing blocks and updates FTL metadata.

### NAND Model

Physical flash geometry and constraints

- [NAND Core](https://github.com/guoruixin123/memoryproject/blob/master/nand.c): physical model · Simulates page program, read, and block erase behavior. · `nand.c`
- [NAND Layout](https://github.com/guoruixin123/memoryproject/blob/master/nand.h): geometry defs · Defines the chip, die, plane, block, and page hierarchy plus OOB layout. · `nand.h`
- **Geometry**: device model · Encodes the 1-chip, 2-die, 2-plane, 4-block, 8-page structure.
- **Page Ops**: granular I/O · Implements page-level program and read constraints.
- **Erase Ops**: block control · Implements block-granularity erase and erase-count updates.
- **OOB Meta**: metadata store · Holds bad-block markers, mapping info, ECC/status fields, and erase counts.
- **Wear State**: lifetime state · Tracks erase history and bad-block behavior across the hierarchy.

### Tooling

Build and supporting artifacts

- [Build](https://github.com/guoruixin123/memoryproject/tree/master/Makefile): toolchain · Builds the simulator with C99 and GCC. · `Makefile`
- [Docs](https://github.com/guoruixin123/memoryproject/blob/master/README.md): guide · Explains the simulator and teaching workflow. · `README.md`
- [Tutorial](https://github.com/guoruixin123/memoryproject/blob/master/TUTORIAL.md): guide · Walks through the learning scenarios and storage concepts. · `TUTORIAL.md`

## Connections

- Main → FTL: logical requests · Host-like commands flow from the demo runner into the translation layer.
- FTL → NAND Core: physical ops · FTL issues page and erase operations to the NAND model.
- FTL → L2P Map: updates · Logical writes and remaps update the translation table.
- FTL → Alloc Policy: allocates · Chooses free pages and applies out-of-place write policy.
- FTL → Bad Blocks: handles · Rejects or remaps failing blocks and preserves usable space.
- NAND Core → NAND Layout: uses layout · The physical model relies on the shared geometry and metadata definitions.
- NAND Layout → Geometry: defines · Captures the simulated flash hierarchy and capacities.
- NAND Core → Page Ops: implements · Programs and reads data at page granularity.
- NAND Core → Erase Ops: implements · Erases blocks and enforces erase-before-write behavior.
- NAND Core → OOB Meta: stores · Persists per-page metadata in the OOB region.
- NAND Core → Wear State: tracks · Maintains erase counts, invalid pages, and bad-block state.
- Main → Logs: prints · The scenario runner emits tagged traces for teaching and inspection.
- FTL → Logs: reports · FTL logs mapping, allocation, and failure decisions.
- NAND Core → Logs: reports · NAND logs constraint checks and low-level operations.
- Build → Main: builds · Build tooling compiles the simulator executable.
- Docs → Tutorial: explains · Documentation supports the teaching-oriented walkthrough.