API Reference

This document provides a comprehensive reference for the API endpoints and functions exposed by OpenNANDLab v2.0.0.

Table of Contents

  1. NAND Simulator (opennandlab.simulator)

  2. Flash Translation Layer (opennandlab.ftl)

  3. NAND Device Model (opennandlab.nand)

  4. Error Correction (opennandlab.ecc)

  5. Defect Management (opennandlab.defect)

  6. Performance Optimization (opennandlab.optimization)

  7. Firmware Integration (opennandlab.firmware)

  8. Analytics & Metrics (opennandlab.analytics)

  9. Configuration (opennandlab.config)

NAND Simulator

NANDController

The NANDController class (in src/opennandlab/simulator.py) is the central orchestrator of OpenNANDLab.

__init__(self, config: SimulatorConfig, interface=None, simulation_mode=False)

Initializes the NAND controller with the provided configuration. Automatically sets up the FTL, ECC handler, bad block manager, wear leveling engine, and other optimizations based on the Pydantic SimulatorConfig.

initialize(self)

Initializes the NAND interface, loads metadata, and runs startup diagnostics.

shutdown(self)

Flushes the cache, saves metadata updates, and shuts down all parallel and physical components. Logs final statistics.

read_page(self, lbn: int) -> bytes

Reads a logical page from the NAND flash. Handles write-buffer lookup, FTL translation, bad block checking, caching, ECC decoding, and decompression.

write_page(self, lbn: int, data: bytes)

Writes data to a logical page. Handles data compression, buffering, ECC encoding, data scrambling, wear leveling updates, and triggers Garbage Collection (GC) if the free pool falls below the threshold.

erase_block(self, block: int)

Erases a physical block and increments its P/E cycle count. Informs the wear leveling engine and invalidates corresponding cache entries.

get_device_info(self) -> dict

Returns information about the NAND device configuration, firmware features, and current performance/health statistics.

Flash Translation Layer

PageFTL

Implements a page-level L2P mapping table using flat integer arrays for extreme efficiency.

__init__(self, num_logical_pages, num_physical_pages, pages_per_block, write_buffer_pages=64)

Initializes the L2P and P2L tables, physical page states, free block deque, and write buffer.

allocate_page(self) -> int

Pops the next available free physical page from the current active block or allocates a new active block from the free pool.

GreedyGC / CostBenefitGC

Garbage Collection policies for reclaiming invalid pages.

run(self, ftl: PageFTL, nand_interface)

Selects a victim block, copies all valid pages to newly allocated free pages, erases the victim block, and returns it to the free block pool.

NAND Device Model

NANDSimulator

Simulates a physical NAND device.

read_page(self, block: int, page: int) -> bytes

Reads raw bytes from the simulated physical block/page array.

write_page(self, block: int, page: int, data: bytes)

Writes raw bytes to the simulated physical array.

erase_block(self, block: int)

Resets the simulated physical block to 0xFF bytes.

reliability.py

Endurance and error models.

rber_model(pe_count: int, cfg: NANDConfig) -> float

Calculates the Raw Bit Error Rate (RBER) based on a Weibull variant model incorporating current P/E cycles and configuration limits (rber_floor, rber_ceil, rber_lambda).

Error Correction

ECCHandler

Unified interface for encoding and decoding data.

encode(self, data: bytes) -> bytes

Encodes data using either BCH or LDPC based on configuration.

decode(self, data: bytes) -> tuple[bytes, int]

Decodes data and returns a tuple of the corrected data and the number of errors corrected.

BCH

__init__(self, m: int, t: int)

Initializes BCH with Galois field size m and error correction capability t. Implements Forney’s algorithm for non-binary correction magnitudes.

LDPC

make_ldpc(n, d_v, d_c, systematic=True, sparse=True)

Generates LDPC parity-check and generator matrices using the Progressive Edge-Growth (PEG) algorithm.

Defect Management

BadBlockManager

mark_bad_block(self, block_address: int)

Marks a physical block as bad.

is_bad_block(self, block_address: int) -> bool

Returns whether a block is marked as bad.

WearLevelingEngine

__init__(self, config)

Initializes the wear leveling engine with a priority queue (min-heap) for \(O(\log N)\) least-worn block lookups.

update_wear_level(self, block_address: int)

Increments the P/E cycle count for the block and updates its position in the heap.

Performance Optimization

DataCompressor

compress(self, data: bytes) -> bytes

Compresses data using LZ4 or Zstandard algorithms.

decompress(self, data: bytes) -> bytes

Decompresses data.

CachingSystem

get(self, key) / put(self, key, value)

Retrieves or caches data using policies such as LRU, LFU, FIFO, or TTL.

Firmware Integration

FirmwareSpecGenerator

generate_spec(self, config=None) -> str

Generates a YAML firmware specification based on template parameters and current constraints.

FirmwareSpecValidator

validate(self, firmware_spec) -> bool

Validates the specification schema and parameter semantics (e.g., block size must be a multiple of page size).

Analytics & Metrics

DataCollector

collect_data(self, num_samples: int, output_file: str)

Collects erase counts and bad block statuses across the simulated NAND layout.

DataAnalyzer

analyze_erase_count_distribution(self) -> dict

Generates statistical distribution metrics (mean, std dev, quartiles) for block erase counts.

Configuration

SimulatorConfig (Pydantic Model)

The central, type-safe configuration object replacing loose YAML dictionaries. Contains nested configuration models:

  • NANDConfig

  • FTLConfig

  • ECCConfig

load_config(config_file: str) -> SimulatorConfig

Loads a YAML file and automatically maps legacy config structures into the new Pydantic SimulatorConfig model.