feat: add a FreeBSD platform (pciconf/devctl/camcontrol/fstat)

Implement the Platform interface with FreeBSD's native tools:

- pciconf -l enumerates devices. Both output formats are parsed: the
  packed chip=/card= fields of 14.3 and earlier, and the split
  vendor=/device= fields of 15.x and 14.4.
- devctl detach / devctl set driver implement unbind and bind for
  kernel drivers. nic_uio cannot be attached that way: it only probes
  devices listed in the hw.nic_uio.bdfs tunable. Binding to nic_uio
  registers the device there, drops any driver pinned by an earlier
  set driver, and (re)loads the module, which detaches the previous
  driver and claims the device by itself. Binding back to a kernel
  driver removes the bdfs entry again.
- camcontrol devlist maps an nvmeX controller to its CAM disk (ndaY),
  so the fstat in-use check also sees users of the disk device.
- kldstat reports whether nic_uio is loaded.
- scan_devices() honors the --device class-filter bypass, matching
  the Linux platform.
- pciconf -w enables bus-mastering once the nic_uio attach is
  verified through pciconf -l. A failed write is reported instead of
  ignored.

Helpers convert between the pciX:B:S:F selector and the
domain:bus:device.function bdf form. nic_uio is added to
KNOWN_DRIVERS, completion, and the docs. User-facing text drops its
Linux assumptions: the --bind help says driver file instead of .ko
file, and the memlock warning says DMA mapping instead of
VFIO_IOMMU_MAP_DMA. Unit tests cover both pciconf formats, the fstat
heuristic, kldstat probing, camcontrol parsing, the nic_uio bdfs
flow, and the devctl bind for kernel drivers.

Signed-off-by: Jaeyoon Choi <j_yoon.choi@samsung.com>

Author: jaeyoon-choi

README.md

@@ -7,12 +7,24 @@
 [![Test](https://github.com/xnvme/devbind/actions/workflows/test.yml/badge.svg)](https://github.com/xnvme/devbind/actions/workflows/test.yml)
 
 `devbind` is a small CLI for binding and unbinding PCI devices to a
-chosen kernel driver via sysfs. The typical use is moving a device
-between its native driver (e.g. `nvme`) and a user space driver
-framework (`vfio-pci`, `uio_pci_generic`) for DPDK/SPDK and xNVMe/uPCIe
-workloads. `devbind --list` also reports the process `RLIMIT_MEMLOCK`
-and warns when the soft limit is below the 64 MiB threshold those
-frameworks inherit.
+chosen kernel driver. The typical use is moving a device between its
+native driver (e.g. `nvme`) and a user space driver framework for
+DPDK/SPDK and xNVMe/uPCIe workloads. `devbind --list` also reports the
+process `RLIMIT_MEMLOCK` and warns when the soft limit is below the
+64 MiB threshold those frameworks inherit.
+
+Both **Linux** and **FreeBSD** are supported; the platform-specific
+operations are handled by a platform implementation selected at runtime:
+
+| | Linux | FreeBSD |
+|---|---|---|
+| enumerate / inspect | `lspci`, sysfs | `pciconf -l`, `camcontrol` |
+| user space framework | `vfio-pci`, `uio_pci_generic` | `nic_uio` |
+| unbind | sysfs `driver/unbind` | `devctl detach` |
+| bind (kernel driver) | sysfs `drivers/<drv>/bind` | `devctl set driver` |
+| bind (user space framework) | sysfs `driver_override` + `bind` | `hw.nic_uio.bdfs` + `kldload` |
+
+(The Linux-only `iommugroup` is reported as `None` on FreeBSD.)
 
 ## Install
 
@@ -33,7 +45,7 @@ curl -fsSL https://raw.githubusercontent.com/xnvme/devbind/main/src/devbind/devb
 devbind --print-completion bash > ~/.local/share/bash-completion/completions/devbind
 ```
 
-Open a new shell (or `source` the file) and tab-completion is live: `devbind --bind <TAB>` lists `nvme vfio-pci vfio-noiommu uio_pci_generic`.
+Open a new shell (or `source` the file) and tab-completion is live: `devbind --bind <TAB>` lists `nvme vfio-pci vfio-noiommu uio_pci_generic nic_uio`.
 
 ## Usage
 
@@ -43,7 +55,7 @@ usage: devbind [-h] [--version] [--classcode CLASSCODE] [--device DEVICE]
                [--list] [--unbind] [--bind BIND] [--verbose]
                [--print-completion SHELL]
 
-Inspect and control PCI device-driver binding in Linux
+Inspect and control PCI device-driver binding on Linux and FreeBSD
 
 options:
   -h, --help            show this help message and exit
@@ -55,8 +67,8 @@ options:
                         association.
   --unbind              Unbind if bound.
   --bind BIND           Unbind if bound; then bind to the given driver-name
-                        [nvme, vfio-pci, uio_pci_generic] or to a .ko driver
-                        file (path)
+                        [nvme, vfio-pci, uio_pci_generic, nic_uio] or to a
+                        driver file (path)
   --verbose             Enable verbose logging
   --print-completion SHELL
                         Print shell completion script to stdout and exit
@@ -71,6 +83,14 @@ sudo devbind --bind nvme --device 0000:01:00.0       # rebind to the native driv
 sudo devbind --unbind --device 0000:01:00.0          # unbind without rebinding
 ```
 
+On FreeBSD, bind to `nic_uio` instead of `vfio-pci`/`uio_pci_generic`
+(`--device` always takes the `domain:bus:device.function` form `0000:01:00.0` on both platforms):
+
+```
+sudo devbind --bind nic_uio --device 0000:01:00.0    # hand device to DPDK/SPDK
+sudo devbind --bind nvme --device 0000:01:00.0       # rebind to the native driver
+```
+
 `devbind --list` sample output (stock WSL host, no NVMe devices visible):
 
 ```

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "devbind"
 dynamic = ["version"]
-description = "Inspect and control PCI device-driver binding in Linux"
+description = "Inspect and control PCI device-driver binding on Linux and FreeBSD"
 readme = "README.md"
 license = "BSD-3-Clause"
 requires-python = ">=3.10"
@@ -18,6 +18,7 @@ classifiers = [
     "Intended Audience :: Developers",
     "Intended Audience :: System Administrators",
     "Operating System :: POSIX :: Linux",
+    "Operating System :: POSIX :: BSD :: FreeBSD",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",