FEMU turns a QEMU fork into an NVMe SSD emulator for systems research

A QEMU fork with SSD backends bolted on

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

The description of what it bridges is the useful part. FEMU bridges the gap between SSD hardware platforms and SSD simulators. It runs the full system stack, meaning applications, the operating system and the NVMe interface, on emulated SSDs of several architectures, each with configurable parameters.

The repository makes the QEMU heritage obvious. The top level contains the same landmarks you would find in QEMU itself, with a Makefile that begins with a comment saying it is the Makefile for QEMU, a configure script, a Kconfig and Kconfig.host, a meson.build, and directories for accel/, audio/, authz/, backends/, crypto/, dump/, ebpf/, fsdev/, chardev/, io/ and the rest of a virtual machine. The FEMU specific work sits in hw/femu/, and the docs live under hw/femu/docs/ alongside scripts, tests and the mode table generator.

So the model is: take a virtual machine, attach an emulated NVMe device instead of a disk, and run the real operating system and the real application on top of it.

The project page is femu-ose.github.io, and there is a PDF manual alongside it. The README opens with an ASCII banner that states the same four adjectives in full:

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

The mode table is the product

FEMU exposes its storage architectures as modes, selected with a femu_mode parameter, and the generated table in the README is the clearest description of what the project is.

NoSSD, femu_mode=2 and the default, is a fast NVMe device in DRAM with no flash timing, started with run-nossd.sh, and it needs nothing beyond the common host requirements. The README's speed claim sits here: in NoSSD mode an I/O completes in a few microseconds to tens of microseconds, depending on the host.

BlackBox SSD, femu_mode=1, models a commercial SSD with a device FTL, garbage collection and NAND timing, and it is the expensive one. It asks for about 17 GiB of free RAM for the launcher's 12 GiB device, and it runs with run-blackbox.sh.

Zoned Namespace, femu_mode=3, is for zoned storage research, needs a guest kernel of 5.9 or newer with CONFIG_BLK_DEV_ZONED=y and 4 KiB guest pages, and expects nvme-cli 1.12 or newer for nvme zns. It starts with run-zns.sh.

Open-Channel SSD 1.2 is femu_mode=0 with lver=1 and Open-Channel SSD 2.0 is femu_mode=0 with lver=2 as the default, both for host-managed FTL research with run-whitebox.sh, on guest kernels from 4.16 or 4.17 up to 5.14, since LightNVM was removed in 5.15. Key-value SSD is femu_mode=5 for key-value store research, on a 6.0 or newer kernel with no block device, where the namespace is /dev/ngXnY. Computational storage is femu_mode=4 with fdm_size, for running programs next to the data.

Each mode is a separate backend under hw/femu/, which is the extensibility claim in concrete form.

Accuracy means charging time back to the workload

The accuracy claim is the one that distinguishes FEMU from a block device that pretends to be an SSD.

The README states that the SSD modes charge NAND, channel and garbage collection time from a configurable timing model. In other words, the emulator does not simply accept a write and return success. It accounts for the time the operation would really have taken on the device being modelled, and the host application sees that cost.

That is what makes the tool useful for research. A file system, a database or a block layer that behaves differently under a slow device can be observed under an emulated slow device, without the researcher owning one. The timing model is documented separately in the concepts section, with the host sizing limits for running several devices and namespaces per VM in another.

The BlackBox mode is the clearest example of the trade. To model a commercial SSD faithfully, the emulator needs a device FTL, garbage collection behaviour and NAND timing, and the launcher allocates a 12 GiB device that wants about 17 GiB of free RAM on the host. That is a large price for realism, and the mode table makes it explicit rather than hiding it.

The NoSSD mode is the opposite end, a DRAM backed device with no flash timing at all, which is what you use when you want the I/O to be fast and you are studying something other than device timing.

Consolidation in 2026, and the AI policy behind it

The README carries a prominent notice about work in progress, and it is the most important paragraph in the file for anyone deciding to build on this.

Features that were previously maintained in separate FEMU based repositories are being ported into this repository, and CXL SSD emulation is already merged as the femu-cxl-ssd device. FEMU is also being made easier to configure, script and drive with AI coding agents, and much of this work is AI-assisted.

The project states its position on that. It believes that careful use of AI-assisted coding, with every change built and regression-tested in CI and reviewed by the maintainers, will help FEMU reach a more organized code structure and better efficiency. A more thorough review is under way in parallel, and in the meantime some existing behavior may change or regress.

That last clause is the one to hold on to. The repository is telling you that behaviour is in motion and that regressions are possible, while asking for bugs, regressions and feature requests through GitHub Issues or the Discord server. It also has a policy document at hw/femu/docs/ai-policy.md, and AI-assisted commits carry an Assisted-by: line, which is a concrete convention for attribution.

Contributions made with your own coding agents are welcome, provided you read the policy first. For a research tool this is a defensible position, since the CI and review requirements are the same ones that would apply to hand-written patches, but it does mean the trust model for a specific commit is the review, not the authorship.

Building it, and where the documentation actually is

The README's advice for newcomers is to start with the FEMU Manual, a PDF that covers building and running FEMU, its architecture and the design of each component, every mode and feature, every parameter, measuring, troubleshooting and contributing, with diagrams throughout.

That is a deliberate choice, and the reason is visible in the table of contents. The README is a long index with the mode table and the project notices, and the detail lives one level down: the full documentation starts at the doc map in hw/femu/docs/, and the same pages are collected in the PDF manual. What changed since the last release is in the changelog at hw/femu/docs/CHANGELOG.md.

The repository also shows the build machinery. The Makefile is the standard QEMU one, with the quiet-command machinery, the config-host.mak include and the dist targets, and a configure script sits at the root next to Kconfig files. The femu-scripts/ directory holds the launcher scripts referenced in the mode table, including run-nossd.sh, run-blackbox.sh, run-zns.sh, run-whitebox.sh and run-kvssd.sh, and the table itself is generated rather than written by hand, produced from hw/femu/docs/modes.py by hw/femu/scripts/gen-mode-table.py.

That last point is worth internalising if you plan to contribute. The comment above the table says to edit modes.py and not the table, so the mode list, its requirements and the README stay in step automatically.

Licence, releases and the gap between the tag and the badge

The licence badge in the README says GPL v2+, and the repository root carries both COPYING and COPYING.LIB, which is the usual pairing for a GPL project that also ships a library exception. The repository listing records the licence as a custom one that GitHub cannot classify, so the COPYING files are the place to confirm the terms rather than the badge.

The release picture needs a second look, because the badge and the tags disagree. The badge reads FEMU v10.1, while the recent releases listed for the repository are femu-v9.0.1 from 2024-06-20, femu-v8.0.0 from 2023-04-25 and femu-v7.0.0 from 2022-04-22.

That gap, more than two years between the last tagged release and the badge, is the signature of a project where the work now lands on the main branch and the release process is being reworked as part of the consolidation. The last push was on 2026-10-18, and the repository is not archived.

For a researcher this has a concrete consequence. If your experiment needs a fixed, citable version, the tags are the only safe references, and they are behind the current code. If you want the CXL SSD device or the new configuration work, you are on the main branch and in the middle of the consolidation, where the README says behaviour may change or regress.

The repository also carries the files a research project needs for governance: CITATION.cff for citation metadata, ROADMAP.md, SECURITY.md, MAINTAINERS, CONTRIBUTING.md and a code of conduct. The project is supported by the US National Science Foundation through NSF POSE award #2550145, Toward a Community-Driven Fast Emulator Ecosystem for Next-Generation Storage Systems Research and Innovation, and the README points to a Discord server for discussion.

Editorial conclusion

FEMU fits a systems researcher or a storage architect who needs to evaluate an FTL, a zoned namespace layout or a computational storage design against a full software stack without hardware, and the per-mode launchers make each architecture a few command line flags away. It is the wrong tool for testing your application against one specific drive you already own, for kernel versions outside the windows the mode table lists, or for anyone who needs a stable release today, since the last tagged release is femu-v9.0.1 from 2024-06-20 while the main branch carries later work. Verify first that your kernel and tools fall inside the requirements for the mode you need, read the changelog for the main branch, and expect the consolidation work to change behaviour, as the README says plainly.

Frequently asked questions

Official sources

1. Issues
2. MoatLab/FEMU on GitHub
3. Project website
4. README
5. Releases