How guoruixin123/memoryproject works
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 NAND Core · ftl.c FTL · main.c Main · nand.h NAND Layout
Components 16
CLI Demo
Scripted scenarios and top-level execution
- Main · Runs the command-line teaching scenarios and drives simulated requests.
main.c - Logs · Tagged output used to explain state transitions step by step.
FTL Layer
Logical-to-physical translation and policy
- FTL · Converts logical requests into physical NAND operations.
ftl.c - L2P Map · Tracks logical block to physical page placement.
- Alloc Policy · Chooses free pages, performs out-of-place writes, and spreads wear.
- Bad Blocks · Skips or marks failing blocks and updates FTL metadata.
NAND Model
Physical flash geometry and constraints
- NAND Core · Simulates page program, read, and block erase behavior.
nand.c - NAND Layout · Defines the chip, die, plane, block, and page hierarchy plus OOB layout.
nand.h - Geometry · Encodes the 1-chip, 2-die, 2-plane, 4-block, 8-page structure.
- Page Ops · Implements page-level program and read constraints.
- Erase Ops · Implements block-granularity erase and erase-count updates.
- OOB Meta · Holds bad-block markers, mapping info, ECC/status fields, and erase counts.
- Wear State · Tracks erase history and bad-block behavior across the hierarchy.
Connections 16
- 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.