FEMU - Fast, Accurate, and Extensible NVMe SSD Emulator

  ______ ______ __  __ _    _
 |  ____|  ____|  \/  | |  | |
 | |__  | |__  | \  / | |  | |
 |  __| |  __| | |\/| | |  | |
 | |    | |____| |  | | |__| |
 |_|    |______|_|  |_|\____/  -- A fast, accurate, scalable, and extensible NVMe SSD Emulator

FEMU is a fast, accurate, scalable, and extensible NVMe SSD emulator based on QEMU/KVM. It enables full-system evaluation of storage systems and supports multiple SSD architectures for systems research.

---

Table of Contents

• Overview
• Features
• Architecture
• System Requirements
• Installation
• Quick Start
• Usage
  • BlackBox SSD Mode (BBSSD)
  • WhiteBox SSD Mode (OCSSD)
  • Zoned Namespace SSD Mode (ZNSSD)
  • NoSSD Mode
• Configuration
• Development
• Troubleshooting
• Research & Citation
• Contributing
• Support
• License
• Acknowledgments

---

Overview

FEMU bridges the gap between SSD hardware platforms and SSD simulators by providing:

• Full system stack support (Applications + OS + NVMe interface)
• Multiple SSD architectures with configurable parameters
• High performance suitable for systems research and development
• Extensible design for exploring new SSD algorithms, architectures, interfaces, and software stacks.

Key Benefits

• ✅ Fast: Sub-10μs latency emulation for performance-critical research
• ✅ Accurate: Realistic SSD behavior modeling based on real hardware characteristics
• ✅ Scalable: Support for large-capacity SSDs and multi-device configurations
• ✅ Extensible: Modular architecture for easy customization and new feature development

---

Features

| Feature | BlackBox | WhiteBox | ZNS | NoSSD | |---------|----------|----------|-----|--------| | FTL Management | Device-side | Host-side | Zone-based | None | | Use Cases | Commercial SSD simulation | OpenChannel SSD research | ZNS research | SCM emulation | | Latency Model | Realistic NAND | Realistic NAND | Zone-optimized | Ultra-low (sub-10μs) | | Guest Support | Full NVMe | OpenChannel 1.2/2.0 | NVMe ZNS | NVMe basic |

---

Architecture

                        +--------------------+
                        |    VM / Guest OS   |
                        |                    |
                        |                    |
                        |  NVMe Block Device |
                        +--------^^----------+
                                 ||
                              PCIe/NVMe
                                 ||
  +------------------------------vv----------------------------+
  |  +---------+ +---------+ +---------+ +-----------+ +------+|
  |  | BlackBox| | WhiteBox| | ZNS-SSD | |  NoSSD    | | ...  ||
  |  |  (BBSSD)| | (OCSSD) | |(ZNSSD)  | |(Ultra-low)| |      ||
  |  +---------+ +---------+ +---------+ +-----------+ +------+|
  |                    FEMU NVMe SSD Controller                |
  +------------------------------------------------------------+
  |                          QEMU/KVM                          |
  +------------------------------------------------------------+
  |                        Host Linux                          |
  +------------------------------------------------------------+

Core Components

• NVMe Controller: Standards-compliant NVMe 1.3+ implementation
• SSD Modes: Pluggable backends for different SSD architectures
• Timing Model: Configurable latency simulation for realistic performance
• Memory Backend: DRAM-based storage emulation

---

System Requirements

Minimum Requirements

• Physical Machine: Run FEMU on a physical machine, not inside a VM (nested virtualization is not recommended due to performance impact)
• OS: Linux (Ubuntu 18.04+, CentOS 7+, or equivalent)
• CPU: x86_64 with hardware virtualization (Intel VT-x/AMD-V)
• Memory: At least 12GB DRAM to enable seamless run of default FEMU scripts emulating a 4GB SSD
• CPU Cores: At least 8 cores for 4 vCPUs and 4GB DRAM VM
• Storage: 20GB free disk space

Recommended Configuration

• CPU: 16+ cores (Intel Xeon or AMD EPYC)
• Memory: 32GB+ RAM
• Storage: NVMe SSD with 100GB+ free space
• Network: For distributed testing scenarios

Host Environment Compatibility

| Linux Distribution | Kernel | GCC | Ninja | Python | Status | |:-------------------|:-------|:-------|:-------|:-------|:-------| | Ubuntu 24.04 LTS | 6.8.0 | 13.2.0 | 1.12.1 | 3.12.3 | ✅ Tested | | Ubuntu 22.04 LTS | 5.15.0 | 11.3.0 | 1.10.1 | 3.10.6 | ✅ Tested | | Ubuntu 20.04 LTS | 5.4.0 | 9.3.0 | 1.10.0 | 3.8.2 | ✅ Tested | | Ubuntu 18.04 LTS | 4.15.0 | 7.5.0 | 1.8.2 | 3.6.7 | ✅ Tested | | Ubuntu 16.04.5 | 4.15.0 | 5.4.0 | 1.8.2 | 3.6.0 | ⚠️ Legacy | | Gentoo | 5.10 | 9.3.0 | 1.10.1 | 3.7.9 | ⚠️ Community |

Guest Environment Compatibility

| Mode \ Guest Kernel | 4.16 | 4.20 | 5.4 | 5.10 | 6.1 | 6.9 | | :--- | :---: | :---: | :---: | :---: | :---: | :---: | | NoSSD | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | BlackBox SSD | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | OpenChannel-SSD v1.2 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | OpenChannel-SSD v2.0 | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ | | Zoned-Namespace (ZNS) SSD | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |

Continuous Integration: FEMU uses GitHub Actions for automated testing across multiple Ubuntu versions. The CI pipeline:

• Tests compilation on Ubuntu 20.04, 22.04, and 24.04 LTS
• Verifies FEMU device registration and all SSD modes (BlackBox, WhiteBox, ZNS, NoSSD)
• Validates code quality and build system integration
• Runs compatibility tests for configuration parameters and run scripts
• Build status is shown in the badge at the top of this README

---

Installation

Build FEMU

1. Clone the repository:

   git clone https://github.com/MoatLab/FEMU.git
   cd FEMU
   

2. Create build directory:

   mkdir build-femu
   cd build-femu
   

3. Setup build environment and install dependencies:

   # Copy FEMU helper scripts
   cp ../femu-scripts/femu-copy-scripts.sh .
   ./femu-copy-scripts.sh .
   
   # Install all build dependencies automatically (Ubuntu/Debian only)
   sudo ./pkgdep.sh
   

4. Compile FEMU:

   ./femu-compile.sh
   

   The FEMU binary will be created as: x86_64-softmmu/qemu-system-x86_64

5. Verify installation:

   ./qemu-system-x86_64 -device help | grep femu
   # Should output: name "femu", bus PCI, desc "FEMU Non-Volatile Memory Express"
   

Build Verification

To ensure your build is successful, run the basic device check:

# Check if FEMU device is properly registered
./qemu-system-x86_64 -device femu,help

# Check version information
./qemu-system-x86_64 --version

---

Quick Start

1. VM Image Setup

Option A: Use Pre-built Image (Recommended)

1. Download VM image from FEMU VM Image Portal
2. Extract to ~/images/ directory
3. Rename to match script expectations: u20s.qcow2

Option B: Build Custom Image

# Create image directory
mkdir -p ~/images
cd ~/images

# Download Ubuntu Server ISO
# If the link no longer works, visit http://releases.ubuntu.com to download the correct version of ISO image
wget http://releases.ubuntu.com/24.04/ubuntu-24.04.3-live-server-amd64.iso

# Create VM disk image
qemu-img create -f qcow2 femu.qcow2 80G

# Install OS (requires GUI environment)
qemu-system-x86_64 -cdrom ubuntu-24.04.3-live-server-amd64.iso \
    -hda femu.qcow2 -boot d -net nic -net user -m 8192 -localtime -smp 8 -cpu host -enable-kvm

2. Configure VM for Serial Console

Inside the VM, edit /etc/default/grub:

sudo nano /etc/default/grub

Add these lines:

GRUB_CMDLINE_LINUX="ip=dhcp console=ttyS0,115200 console=tty console=ttyS0"
GRUB_TERMINAL=serial
GRUB_SERIAL_COMMAND="serial --unit=0 --speed=115200 --word=8 --parity=no --stop=1"

Update GRUB and reboot:

sudo update-grub
sudo reboot

3. Run Your First FEMU Instance

# From the build-femu directory
./run-blackbox.sh

4. Access the VM

The VM will start in text mode. You can also SSH into the VM:

# From host machine
ssh -p 8080 username@localhost

---

Usage

FEMU supports multiple SSD emulation modes, each optimized for different research scenarios.

BlackBox SSD Mode (BBSSD)

Emulates commercial SSDs with device-managed FTL.

./run-blackbox.sh

Key Parameters:

# SSD Layout Configuration
secsz=512              # Sector size (bytes)
secs_per_pg=8          # Sectors per page
pgs_per_blk=256        # Pages per block
blks_per_pl=256        # Blocks per plane
luns_per_ch=8          # LUNs per channel
nchs=8                 # Number of channels

# Performance Configuration
pg_rd_lat=40000        # Page read latency (ns)
pg_wr_lat=200000       # Page write latency (ns)
blk_er_lat=2000000     # Block erase latency (ns)

# Garbage Collection
gc_thres_pcent=75      # GC trigger threshold

Use Cases:

• Commercial SSD simulatio