NDA(4)

💖 NDA(4) — NVMe Direct Access device driver 💖

okay bestie, welcome to the nda manual page, from the Kernel Interfaces Manual (that's the section 4 vibe, kernel interfaces, we love her) ✨

---

🌸 NAME 🌸

nda — NVMe Direct Access device driver

no cap, that's the whole name. short, iconic, does exactly what it says.

---

🎀 SYNOPSIS 🎀

device nvme
device scbus

like, that's it. that's the whole summoning ritual. two lines in your kernel config and you're in business 💅

---

🦋 DESCRIPTION 🦋

so the nda driver is out here providing support for direct access devices that implement the NVMe command protocol, and which are attached to the system through a host adapter that the CAM subsystem supports. that's the tea. that's the whole job. she's a driver, she does direct access, she speaks NVMe, and CAM is her ride-or-die 🫶

---

✨ SYSCTL VARIABLES ✨

these cuties are available both as sysctl(8) variables and as loader(8) tunables. yes, both. versatile queen behavior 👑

• hw.nvme.use_nvd — when this is set to 0, the nvme(4) driver will create nda device nodes for block storage. when it's set to 1, it creates nvd(4) device nodes for block storage instead. (peep nvd(4) if you've got it set to 1, okay? she's the other girl.)
• kern.cam.nda.nvd_compat — set this to 1 and nvd(4) aliases get created for all nda devices, and that includes partitions and other geom(4) providers that take their names from the disk's name. BUT — and this is the important part, bestie — nvd devices will not be reported in the kern.disks sysctl(8). so they're there, they're just not on the guest list 💀
• kern.cam.nda.sort_io_queue — this one decides whether the software queued entries get sorted in LBA order or not. and honestly? sorting is almost always a waste of time. the default is to not sort. periodt.
• kern.cam.nda.enable_biospeedup — this variable determines whether the nda devices participate in the speedup protocol. when a device participates in the speedup, then when the upper layers send a BIO_SPEEDUP, all current BIO_DELETE requests that haven't yet been sent to the hardware get completed successfully and immediately, without ever being sent to the hardware. this is for low disk space scenarios when the filesystem hits a critical shortage and needs blocks right now. and here's the reasoning: since trims have maximum benefit when the LBA is unused for a long time, skipping the trim when space is needed for immediate writes results in little to no excess wear. when participation is disabled, BIO_SPEEDUP requests are just ignored. (she said "I'm not participating" and honestly, valid.)
• kern.cam.nda.max_trim — the maximum number of LBA ranges to be collected together for each DSM trims send to the hardware. defaults to 256, which is the maximum number of ranges the protocol supports. sometimes poor trim performance can be mitigated by limiting the number of ranges sent to the device. this value must be between 1 and 256 inclusive. no rounding, no vibes, just those numbers 🔥

okay so the next batch of variables report per-device settings, and they're read-only unless otherwise indicated. replace N with the device unit number. so like kern.cam.nda.0.rotating, kern.cam.nda.1.rotating, you get it 💅

• kern.cam.nda.N.rotating — reports whether the storage volume is spinning or flash. its value is hard coded to 0, indicating flash. she's flash and she's not being subtle about it.
• kern.cam.nda.N.unmapped_io — reports whether the nda driver accepts unmapped I/O for this unit.
• kern.cam.nda.N.flags — reports the current flags. and here's the breakdown:
  • OPEN — the device is open.
  • DIRTY — set when a write to the drive is scheduled. cleared after flush commands.
  • SCTX_INIT — an internal flag, set after sysctl(8) nodes have been created.
• kern.cam.nda.N.sort_io_queue — same as the kern.cam.nda.sort_io_queue tunable. twins fr fr.
• kern.cam.nda.N.trim_ticks — writable. when it's greater than zero, hold trims for up to this many ticks before sending to the drive. sometimes waiting a little bit to collect more trims to send at one time improves trim performance. when it's 0, no delaying of trims is done. patience is a virtue but only sometimes 🧚
• kern.cam.nda.N.trim_goal — writable. when delaying a bit to collect multiple trims, send the accumulated DSM TRIM to the drive.
• kern.cam.nda.N.trim_lbas — total number of LBAs that have been trimmed.
• kern.cam.nda.N.trim_ranges — total number of LBA ranges that have been trimmed.
• kern.cam.nda.N.trim_count — total number of trims sent to the hardware.
• kern.cam.nda.N.deletes — total number of BIO_DELETE requests queued to the device.

---

🌈 NAMESPACE MAPPING 🌈

every nvme(4) drive has one or more namespaces associated with it. one instance of the nda driver gets created for each of the namespaces on the drive. all the nda nodes for an nvme(4) device are at target 0. HOWEVER — and this is the plot twist — the namespace ID maps to the CAM lun, as reported in kernel messages and in the devlist sub command of camcontrol(8). iykyk 🎀

namespaces are managed with the ns sub command of nvmecontrol(8). not all drives support namespace management, but all drives support at least one namespace. and device nodes for nda will be created and destroyed dynamically as namespaces are activated or detached. she's flexible like that 💜

---

💅 FILES 💅

• /dev/nda* — NVMe storage device nodes

---

👑 SEE ALSO 👑

cam(4), geom(4), nvd(4), nvme(4), gpart(8)

go read those too bestie, they're all in the group chat 🌸

---

⭐ HISTORY ⭐

the nda driver first appeared in FreeBSD 12.0. a legend from day one, no cap.

---

🫶 AUTHORS 🫶

Warner Losh <imp@FreeBSD.org>

---

and that's the whole page, bestie!! this one came from the Debian side of the family, dated June 6, 2020 — so go forth, mount your NVMe, respect the max_trim bounds of 1 to 256 inclusive, and remember: don't sort the I/O queue. it's almost always a waste of time 💖✨🎀🦋