RISC-V Bare-Metal NVMe Controller

QEMU virt 머신 위에서 OS 없이 동작하는 미니 NVMe SSD 컨트롤러 펌웨어. 부팅, 트랩, NVMe 커맨드 처리, FTL, GC, NAND 시뮬레이션을 전부 직접 구현해 RISC-V CPU에서 돌린다.

학습 목표

"SSD 안에서 도는 펌웨어"를 직접 짜보면서 다음을 손으로 익히는 게 목적이다.

• RISC-V 베어메탈 런타임 — 리셋 벡터, 스택/BSS, linker script, M-mode CSR, 트랩 벡터, freestanding C (libc 없음)
• NVMe 프론트엔드 — SQ/CQ 자료구조, Admin(Identify, Create I/O Queue)·I/O(Read/Write) 커맨드 처리
• FTL — page-level L2P/P2L 매핑, out-of-place update, over-provisioning
• GC + NAND 특성 — write-before-erase, greedy victim 선정, host write 경로 안에서의 매핑 일관성, WAF 측정

FEMU가 SSD를 위에서 보는 시점이라면 이 프로젝트는 안에서 보는 시점이다. 둘 다 경험하면 SSD 스택을 위·아래 모두에서 보게 된다.

빌드 / 실행

riscv64-unknown-elf-gcc, qemu-system-riscv64 필요.

make            # firmware.elf 생성
make run        # QEMU 부팅, UART 출력 → 터미널
make debug      # gdbstub :1234 로 정지 부팅
                # gdb-multiarch firmware.elf -ex 'target remote :1234'

테스트 프레임워크는 없다. src/main.c가 직접 I/O SQ에 커맨드를 enqueue하고 nvme_poll()을 돌리며 FTL/GC를 회귀 검증한다. 새 소스 추가 시 Makefile의 SRCS_C/SRCS_S에 등록.

구조

src/boot/    start.S, trap_vector.S
src/drivers/ uart, clint, trap
src/nvme/    nvme.c (큐), nvme_admin.c, nvme_io.c
src/ftl/     ftl.c, gc.c
src/nand/    nand_sim.c
src/lib/     freestanding string.c
src/main.c   부팅 후 테스트 워크로드
include/     공용 헤더
linker.ld    메모리 레이아웃 (RAM 0x80000000, 128 MiB, 16 KiB stack)

핵심 파라미터

항목	값	정의
NAND geometry	256 blk × 64 pg × 4096 B = 16384 pg	nand_sim.h
Host LBA 수	13107 (80%, 나머지 20% OP)	NVME_MAX_LBAS
LBA size	4096 B (= page size)	NVME_LBA_SHIFT = 12
Queue depth	64	QUEUE_DEPTH
GC 트리거	free block < 10	GC_THRESHOLD_BLOCKS

진행 단계

태그	단계
v0.0-boot	부트 + UART
v0.1-trap	트랩 + 타이머
v0.2-nvme	NVMe Admin
v0.3-ftl	FTL + I/O
v0.4-gc	Garbage Collection (현재)
v0.5-zns	ZNS 확장 (선택)

커밋 컨벤션

<type>(<scope>): <lowercase imperative>

• type: feat, fix, refactor, docs, test, chore
• scope: boot, uart, trap, nvme, ftl, gc, nand, zns