feat: add FreeBSD support

[jaeyoon-choi]

Summary

Add FreeBSD support to devbind. A backend picked at runtime maps the same
CLI onto each platform's native tooling, so one command prepares an NVMe
device for xNVMe on both Linux and FreeBSD. Verified
end-to-end on FreeBSD 15.1 and 14.4 VMs with an emulated NVMe device, and
re-verified on Linux the same way. The branch is structured for per-commit
review; every commit passes the test suite on its own.

Details

xNVMe support FreeBSD, but preparing a device there — loading
nic_uio, running devctl detach and devctl set driver, enabling
bus-mastering by hand — was manual. devbind covered only Linux, with the
sysfs paths hardcoded in the tool.

The Linux code now sits behind a small Backend interface, and a FreeBSD
implementation joins it:

operation	Linux	FreeBSD
enumerate / inspect	lspci, sysfs	pciconf -l
unbind / bind	sysfs unbind / bind	devctl detach / devctl set driver
in-use check	lsof	fstat + camcontrol (nvmeX → ndaY)
userspace driver	vfio-pci, uio_pci_generic	nic_uio
bus-mastering	setpci	pciconf -w

FreeBSD has no VFIO, so nic_uio (the uio_pci_generic analogue) is the
userspace path there, and iommugroup reports None. Naming a driver the
running platform does not have is rejected before the device is touched.

The five commits, bottom to top:

1. fix: the 0.3.10 --device lookup read an unmapped key and matched
   nothing
2. refactor: decouple scanning and binding from argparse
3. refactor: move the Linux code onto a LinuxBackend class. A pure
   move. Output on Linux is unchanged. Easiest to read with
   --color-moved.
4. fix: backend errors exit with a one-line message instead of a
   traceback
5. feat: the FreeBSD backend, unit tests for both platforms, and docs

Two notes for review:

• pciconf -l output differs by release. 14.3 and earlier print packed
  chip=/card= fields. 15.x and 14.4 print split vendor=/device=
  fields. Both are parsed, and the unit fixtures cover both.
• The in-use check finds the CAM disk (ndaY) behind an nvmeX controller
  via camcontrol devlist. Anyone holding the disk open blocks
  unbinding. Legacy nvd(4) disks do not attach via CAM, so the check does
  not see them. The code documents this limit.

[karlowich]

This brings us halfway to drop xnvme-driver (SPDK's setup.py) on FreeBSD.
We also need to handle the contigmem part (DPDK's solution to the missing hugepages on FreeBSD):

From SPDK setup.py:

function _configure_freebsd() {
	local freebsd_bufsz=${FREEBSD_BUFSZ:-256}

	if ! check_for_driver_freebsd; then
		echo "DPDK drivers (contigmem and/or nic_uio) are missing, aborting" >&2
		return 1
	fi
	configure_freebsd_pci "$@"
	if [[ $SKIP_HUGE == yes ]]; then
		# Do nothing as requested
		return 0
	fi
	# If contigmem is already loaded but the HUGEMEM specified doesn't match the
	#  previous value, unload contigmem so that we can reload with the new value.
	if kldstat -q -m contigmem; then
		# contigmem may be loaded, but the kernel environment doesn't have to
		# be necessarily set at this point. If it isn't, kenv will fail to
		# pick up the hw. options. Handle it.
		if ! contigmem_num_buffers=$(kenv hw.contigmem.num_buffers); then
			contigmem_num_buffers=-1
		fi 2> /dev/null
		if ((contigmem_num_buffers != HUGEMEM / freebsd_bufsz)); then
			kldunload contigmem.ko
		fi
	fi
	if ! kldstat -q -m contigmem; then
		kenv hw.contigmem.num_buffers=$((HUGEMEM / freebsd_bufsz))
		kenv hw.contigmem.buffer_size=$((freebsd_bufsz * 1024 * 1024))
		kldload contigmem.ko
	fi
}

@safl Do you think we should put the contigmem part in devbind too? Or perhaps it needs a separate tool and repo.

[karlowich]

Great.
I propose adding the test_linux.py in a later commit, to avoid changing the test in 3 consecutive commits.

Also see the few inline comments.

[karlowich]

I think this should be called platform instead. That puts it more in line with the doc-string: "Platform-specific PCI device-driver binding operations"

[karlowich]

Let's rename backend to platform here too.

[karlowich]

if we rename from backend to platform, then this class could just be named Linux

[karlowich]

This should be renamed

[safl]

This brings us halfway to drop xnvme-driver (SPDK's setup.py) on FreeBSD. We also need to handle the contigmem part (DPDK's solution to the missing hugepages on FreeBSD):

From SPDK setup.py:

function _configure_freebsd() {
	local freebsd_bufsz=${FREEBSD_BUFSZ:-256}

	if ! check_for_driver_freebsd; then
		echo "DPDK drivers (contigmem and/or nic_uio) are missing, aborting" >&2
		return 1
	fi
	configure_freebsd_pci "$@"
	if [[ $SKIP_HUGE == yes ]]; then
		# Do nothing as requested
		return 0
	fi
	# If contigmem is already loaded but the HUGEMEM specified doesn't match the
	#  previous value, unload contigmem so that we can reload with the new value.
	if kldstat -q -m contigmem; then
		# contigmem may be loaded, but the kernel environment doesn't have to
		# be necessarily set at this point. If it isn't, kenv will fail to
		# pick up the hw. options. Handle it.
		if ! contigmem_num_buffers=$(kenv hw.contigmem.num_buffers); then
			contigmem_num_buffers=-1
		fi 2> /dev/null
		if ((contigmem_num_buffers != HUGEMEM / freebsd_bufsz)); then
			kldunload contigmem.ko
		fi
	fi
	if ! kldstat -q -m contigmem; then
		kenv hw.contigmem.num_buffers=$((HUGEMEM / freebsd_bufsz))
		kenv hw.contigmem.buffer_size=$((freebsd_bufsz * 1024 * 1024))
		kldload contigmem.ko
	fi
}

@safl Do you think we should put the contigmem part in devbind too? Or perhaps it needs a separate tool and repo.

Yeah, separate tool. Since, the main thing about the suite of tools: devbind, hugepages, iommu, etc. are that instead of a single monolithic setup.sh or xnvme-driver then the tools manage one specific task. If it were to be squeezed in anywhere, then it would be in the hugepages tool. The challenge of course is that currently then these tools are inherently Linux specific, however, the devbind tool should have equivalent functionality of scanning the pcie, changing driver association etc. but yeah... a dedicated "configmem" tool is preferable.