NVMe Educational Driver (nvmedu)

WARNING: FOR EDUCATIONAL USE ONLY

This driver is designed for learning NVMe protocol and Linux kernel driver development. DO NOT use this driver in production environments or with important data.

Overview

nvmedu is a minimal NVMe over PCIe host driver implementation created for educational purposes. It demonstrates the core concepts of NVMe protocol, including:

• NVMe Admin and I/O queue management
• Scatter-Gather List (SGL) implementation
• Block layer integration with blk-mq
• PCI device driver fundamentals
• Interrupt handling and completion processing

Features

• Supported Operations: READ, WRITE, FLUSH, WRITE_ZEROES
• Single Namespace: nsid=1 only
• SGL Support: Uses Scatter-Gather Lists for data transfer
• Multiple I/O Queues: Scales with CPU count
• QEMU Compatible: Tested with QEMU NVMe emulation
• Amazon EBS Ready: Includes quirks for AWS NVMe devices

Development Environment

This driver was developed and tested on:

• Guest Kernel: 6.16.0-rc1
• QEMU: 9.2.4

Building and Usage

Build

make

Load the driver

sudo insmod nvmedu.ko

Note: If the device is already bound to the standard nvme driver, you need to unbind it first:

# Check which driver is currently bound
lspci -k | grep -A 3 "Non-Volatile memory controller"

# Unbind from nvme driver (replace with your device's PCI address)
echo 0000:00:04.0 > /sys/bus/pci/drivers/nvme/unbind

Unload the driver

sudo rmmod nvmedu

QEMU Testing Example

This is an example of the test environment used during development:

Test Environment

• Guest Kernel: 6.16.0-rc1
• QEMU: 9.2.4

Creating Test Image

# Create 1GB NVMe test image
qemu-img create -f raw nvme.img 1G

Example QEMU Command

qemu-system-x86_64 \
  -nographic \
  -display none \
  -cpu host \
  -kernel /path/to/bzImage \
  -drive file=/path/to/rootfs.ext4,format=raw,index=1,media=disk,if=virtio,cache=none \
  -append "console=ttyS0 audit=0 selinux=0 root=/dev/vda" \
  -accel kvm \
  -device nvme,drive=nvme0,serial=deadbeef \
  -drive file=nvme.img,if=none,id=nvme0

Note: This is just one example setup. Other QEMU configurations should work as well.

Safety Warnings

NEVER use this driver with important data
Test only in isolated environments
Always backup data before testing
Not suitable for production use

This driver is intentionally simplified for educational purposes and lacks many production-grade features like robust error recovery, extensive validation, and performance optimizations.

License

This project is licensed under the GNU General Public License v2.0 - see the kernel's COPYING file for details.

---

Educational Use Only - This driver is designed for learning and experimentation. For production NVMe devices, use the official Linux NVMe driver (drivers/nvme/).