{"id":31355141,"url":"https://github.com/wipeseals/znvme","last_synced_at":"2025-09-26T16:49:11.116Z","repository":{"id":313798848,"uuid":"1006020719","full_name":"wipeseals/znvme","owner":"wipeseals","description":"A userspace NVMe driver written in Zig.","archived":false,"fork":false,"pushed_at":"2025-09-08T14:30:51.000Z","size":206,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-08T15:37:14.747Z","etag":null,"topics":["driver","nvme","ssd","vfio","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wipeseals.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-21T10:05:39.000Z","updated_at":"2025-08-23T20:27:06.000Z","dependencies_parsed_at":"2025-09-08T15:37:18.167Z","dependency_job_id":"dc3b7430-be2f-41c5-9dfb-63baa3e289b3","html_url":"https://github.com/wipeseals/znvme","commit_stats":null,"previous_names":["wipeseals/znvme"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/wipeseals/znvme","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wipeseals%2Fznvme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wipeseals%2Fznvme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wipeseals%2Fznvme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wipeseals%2Fznvme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wipeseals","download_url":"https://codeload.github.com/wipeseals/znvme/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wipeseals%2Fznvme/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277112107,"owners_count":25762969,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-26T02:00:09.010Z","response_time":78,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["driver","nvme","ssd","vfio","zig"],"created_at":"2025-09-26T16:49:08.881Z","updated_at":"2025-09-26T16:49:11.106Z","avatar_url":"https://github.com/wipeseals.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# znvme\n\n[![zig test](https://github.com/wipeseals/znvme/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/wipeseals/znvme/actions/workflows/test.yml)\n\nA userspace NVMe driver implemented in Zig, leveraging VFIO for direct hardware access.\n\n## Features\n\n- Direct access to NVMe device registers and features from user space.\n- Secure operation without sudo by using VFIO.\n- Easy integration with Zig applications.\n\n## Requirements\n\n- Zig 0.14.1 or later\n- Linux kernel with `vfio-pci` support\n    - IOMMU enabled in the kernel (Intel VT-d or AMD-Vi)\n- NVMe devices connected to the system\n\n## Installation\n\nTo use this library, you need to clone the repository and build the Zig package.\n\n```bash\ngit clone https://github.com/wipeseals/znvme.git\ncd znvme\nzig build test\n```\n\n## Usage\n\n\n### Basic Example\n\nTODO\n\n### Advanced Example\n\nTODO\n\n## IOMMU Setup\n\nEnsure the kernel command line includes `intel_iommu=on` or `amd_iommu=on` depending on your CPU architecture.\n\n```bash\ncat /proc/cmdline\nsudo dmesg | grep -e DMAR -e IOMMU\n```\n\n```bash\nuser in 🌐 nbg9 in znvme on  develop [$✘?] via ↯ v0.14.1 via ❄️  impure (nix-shell-env) \n❯ sudo dmesg | grep -e DMAR -e IOMMU\n(snip)\n[    0.005995] ACPI: DMAR 0x00000000725CE000 000088 (v02 INTEL  EDK2     00000002      01000013)\n[    0.006037] ACPI: Reserving DMAR table memory at [mem 0xXXXXXXXX-0xXXXXXXXX]\n[    0.027230] DMAR: IOMMU enabled\n[    0.079635] DMAR: Host address width 39\n```\n\n#### For Intel CPUs\n\nAdd `intel_iommu=on` to the kernel command line in your bootloader configuration (e.g., GRUB):\n\n```bash\nsudo vim /etc/default/grub\n```\n\n```text\nGRUB_CMDLINE_LINUX_DEFAULT=\"quiet splash intel_iommu=on\"\n```\n\nThen update GRUB\n\n```bash\nsudo update-grub\n```\n\n\n\n## VFIO Setup\n\nTo access NVMe devices from user space, you need to switch the kernel driver from `nvme` to `vfio-pci`.\n\nDriver switching scripts are available in the `misc/` directory.\n\n#### Listing NVMe devices\n\nFirst, check the NVMe devices connected to your system.  \nThe following command lists devices currently bound to the `nvme` driver:\n\n```bash\nuser in 🌐 nbg9 in znvme on  master [!?] via ↯ v0.14.1 via ❄️  impure (nix-shell-env) \n❯ sudo ./misc/list.sh\n# Listing NVMe devices\nNode                  Generic               SN                   Model                                    Namespace  Usage                      Format           FW Rev  \n--------------------- --------------------- -------------------- ---------------------------------------- ---------- -------------------------- ---------------- --------\n/dev/nvme0n1          /dev/ng0n1            Z4HF716NF88S         KIOXIA-EXCERIA with Heatsink SSD         0x1          1.02  TB /   1.02  TB    512   B +  0 B   AJRA4101\n/dev/nvme1n1          /dev/ng1n1            201008800819         WDC WD BLACK SDBPNTY-512G-1106           0x1        512.11  GB / 512.11  GB    512   B +  0 B   HPS2    \n/dev/nvme2n1          /dev/ng2n1            TTSMA2513X09608      TWSC TSC3AN512-F8T40S                    0x1        512.11  GB / 512.11  GB    512   B +  0 B   SN13126 \n\n# Listing NVMe devices with PCI addresses, VID, PID, and manufacturer/model info\nPCI Address: 01:00.0, VID: 15b7, PID: 5006, Info: Sandisk Corp SanDisk Extreme Pro / WD Black SN750 / PC SN730 / Red SN700 NVMe SSD\nPCI Address: 06:00.0, VID: 1e0f, PID: 000d, Info: KIOXIA Corporation NVMe SSD Controller XG7\nPCI Address: 07:00.0, VID: 1e4b, PID: 1202, Info: MAXIO Technology (Hangzhou) Ltd. NVMe SSD Controller MAP1202 (DRAM-less) (rev 01)\n```\n\nYou can also check each device's PCI address, vendor ID, and product ID.  \nThis information is required for driver switching.\n\n#### Binding to the vfio-pci driver\n\nUnbind the NVMe device from the `nvme` driver and bind it to the `vfio-pci` driver.  \nExample for switching the device at PCI address `0000:06:00.0`:\n\n```bash\nuser in 🌐 nbg9 in znvme on  master [!?] via ↯ v0.14.1 via ❄️  impure (nix-shell-env) \n❯ sudo ./misc/bind_vfio.sh 0000:06:00.0 1e0f 000d\nUnbound 0000:06:00.0 from nvme driver.\ngrep: /sys/bus/pci/drivers/vfio-pci/new_id: Permission denied\nBound 0000:06:00.0 to vfio-pci driver.\nBound 0000:06:00.0 to vfio-pci driver.\nSuccessfully bound 0000:06:00.0 to vfio-pci driver.\n06:00.0 Non-Volatile memory controller: KIOXIA Corporation NVMe SSD Controller XG7\n        Subsystem: KIOXIA Corporation NVMe SSD Controller XG7\n        Kernel driver in use: vfio-pci\n        Kernel modules: nvme\n```\n\nIf you see `Permission denied` for `/sys/bus/pci/drivers/vfio-pci/new_id`, make sure you are running as root.  \nAfter binding, confirm `Kernel driver in use: vfio-pci`.\n\n\n#### Unbinding from the vfio-pci driver and rebinding to the nvme driver\n\nAfter your work, you can return the device to the original `nvme` driver:\n\n```bash\nuser in 🌐 nbg9 in znvme on  master [!?] via ↯ v0.14.1 via ❄️  impure (nix-shell-env) \n❯ sudo ./misc/unbind_vfio.sh 0000:06:00.0\nUnbound 0000:06:00.0 from vfio-pci driver.\nBound 0000:06:00.0 to nvme driver.\nSuccessfully bound 0000:06:00.0 to nvme driver.\n06:00.0 Non-Volatile memory controller: KIOXIA Corporation NVMe SSD Controller XG7\n        Subsystem: KIOXIA Corporation NVMe SSD Controller XG7\n        Kernel driver in use: nvme\n        Kernel modules: nvme\n```\n\n## References\n\n- [NVMe Specification](https://nvmexpress.org/specifications/)\n  - [NVM Express Base Specification Revision 2.1](https://nvmexpress.org/wp-content/uploads/NVM-Express-Base-Specification-Revision-2.1-2024.08.05-Ratified.pdf)\n  - [NVM Express PCI Express Transport Specification Revision 1.1](https://nvmexpress.org/wp-content/uploads/NVM-Express-PCI-Express-Transport-Specification-Revision-1.1-2024.08.05-Ratified.pdf)\n\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwipeseals%2Fznvme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwipeseals%2Fznvme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwipeseals%2Fznvme/lists"}