FreeBSD fwget Operations: Detect and Install Required Firmware Packages

Some FreeBSD device drivers require a firmware image supplied as a separate package. The fwget utility can inspect supported hardware in a running system and identify firmware packages needed by devices. It is an installation aid, not a general firmware flasher: the documented utility installs firmware packages for recognized PCI and USB devices, while firmware loading and device support remain responsibilities of the driver and kernel.

The distinction matters during hardware triage. A PCI or USB function can enumerate correctly while its driver lacks a required firmware image. Conversely, installing a package does not prove that the driver bound to the device, loaded the image, initialized the hardware, or provided a working service. Validate the complete chain from enumeration to driver attach and application-level operation.

Establish a hardware and release baseline

Record the system release, supported buses, and device attach messages before installing anything:

freebsd-version -kru
pciconf -lv
usbconfig
dmesg | tail -160
service -e

Use the output to identify the actual subsystem and device. fwget’s manual documents PCI and USB as the currently supported subsystems, so it should not be assumed to inspect every bus or firmware-loading mechanism. The tool’s supported set can change; verify the local manual on the exact release.

Inspect the relevant driver’s manual page for firmware requirements and attach diagnostics. A generic firmware package can support a family of devices, but the driver may require a particular package name, file path, module, or firmware revision. Do not infer hardware support from a package search result or a vendor marketing list. The FreeBSD driver manual and current release notes define the supported combination.

Preserve dmesg and device inventory before a change. If the device already works, avoid installing speculative firmware packages solely because the hardware appears in an inventory. If the device fails, capture the exact attach error, driver name, PCI vendor/device ID or USB vendor/product ID, and firmware file message before changing package state.

Preview fwget’s package plan

Use the dry-run option first. With no subsystem argument, fwget considers all supported subsystems; a narrower PCI or USB selection can reduce the plan:

fwget -n
fwget -n pci
fwget -n usb

The dry run reports needed firmware packages without installing them. Compare its output with the driver’s manual, the current package repository, the host’s package policy, and the hardware owner. The command detects packages for devices present on the running system; it is not a guarantee that every attached device needs firmware or that a proposed package will fix a specific failure.

Review package names and repository configuration before proceeding. A production host may be pinned to a quarterly repository, use an internal repository, or run without direct network access. Do not switch repositories just to make fwget succeed without reviewing compatibility. The package plan is only useful if the firmware artifact comes from the intended repository and matches the FreeBSD branch and driver.

If the dry run shows no package, investigate other causes: unsupported hardware, a missing or unloaded driver, firmware embedded in a different package, incorrect device identification, a failed bus attach, or firmware managed outside fwget’s supported PCI/USB path. A no-op result does not certify that the device is supported or fully initialized.

Do not run fwget against a hardware inventory that has not been reviewed. A USB device can be attached temporarily for provisioning, while a PCI device can belong to a virtual machine, a passthrough plan, or a disabled feature. Compare the proposed package set with the service owner’s intended hardware role and the system’s package manifest. If a device is not required, the operational choice may be to remove or disable it through its supported management path rather than install a dependency for every detected function.

Firmware package selection is a mapping from hardware identity to package metadata, not proof that the package is the latest image or that every hardware revision behaves identically. Record both the package name printed by fwget and the repository from which pkg resolves it. If the host uses a custom repository, confirm that its package manifest and ABI match the target FreeBSD release. Keep the dry-run output with the change request so an unexpected package name can be reviewed before installation.

Install the reviewed packages

When the package list is approved and repository access is correct, run fwget without -n for the intended subsystem:

fwget pci

Or, if the planned devices are USB-backed:

fwget usb

Use a scoped call only when the selected subsystem is deliberate. Without an argument, the utility defaults to all supported subsystems. Installing packages changes system state and may trigger package scripts; follow the host’s normal package change process, preserve the transaction output, and do not automate acceptance of an unreviewed package list.

The utility installs firmware packages; it does not flash new firmware into the device’s nonvolatile storage. Do not describe fwget as a device firmware updater. Firmware package contents provide images for the driver to load according to its implementation. A vendor’s BIOS, SSD controller, network adapter, or peripheral update may require a distinct tool and maintenance procedure.

After installation, inspect package state and available files without guessing their paths:

pkg info
pkg info -l REPLACE_WITH_FIRMWARE_PACKAGE

Replace the placeholder with the exact package name from fwget output. pkg info -l shows files installed by a named package; a firmware image may be under a location different from the kernel module path. Do not use package file presence as proof that the driver loaded the image.

The package lifecycle remains the normal pkg lifecycle. Future package upgrades, branch changes, or repository migrations may replace firmware files, change dependencies, or remove a package that fwget originally selected. Keep a record of which hardware requires each package and include those packages in normal host inventory and recovery planning. A host rebuilt from a minimal manifest may otherwise boot without the firmware needed for networking or storage access.

Do not pin firmware packages indefinitely without considering the matching kernel and driver. A package can be present while the running kernel expects another interface or while the driver is too old to use the image. Conversely, package removal may leave a device unavailable on the next driver attach. Treat the package, kernel module, hardware revision, and release as a compatibility set and revalidate it after major upgrades.

Activate and verify the driver path

Some drivers load firmware when the device attaches, when the module loads, or during a later initialization stage. Check the driver manual and kernel messages to learn which event applies. A package installation may not cause an already-attached device to reload its firmware. Reloading a driver or rebooting can interrupt a network interface, storage controller, or other critical device, so schedule it with an alternate access path and an approved recovery plan.

After the approved activation step, inspect device attachment again:

dmesg | tail -160
pciconf -lv
usbconfig
ifconfig -a

Only use the commands relevant to the device. For a network interface, verify link, address configuration, route, and a real application connection. For storage, verify the controller, namespace or disk node, GEOM consumers, and filesystem health. For radio devices, test the intended mode and traffic path. A firmware-loaded message is one checkpoint, not an end-to-end functional test.

The correct post-install test is specific to the component. A wireless driver may attach but fail association; a network controller may show link but still have packet errors; a storage controller may enumerate but expose no expected namespace. Use the dedicated driver and service runbook to verify the layer above attach. When possible, compare the same host before and after the package change using identical cables, access point, storage enclosure, workload, and operating conditions.

If the device fails after a module reload, preserve the full log, package list, kernel and userland versions, hardware identifiers, and driver name. Restore the prior package or module state only according to the supported package and kernel procedure. Do not delete firmware files by hand to force the driver into another path.

Common failure patterns

fwget is missing. Check the FreeBSD release and installed base-system files, then consult the local fwget manual. Do not install a third-party utility with the same name without confirming provenance.

Dry run returns no packages. Confirm the device is on PCI or USB, identify its exact vendor/device ID, check the driver support list, and review attach messages. The utility only covers supported subsystems and recognized package mappings.

Package installation fails. Inspect repository reachability, package ABI, branch, local repository policy, and the exact pkg error. Do not change the host’s repository configuration as a blind workaround. A missing package may reflect a repository mismatch or absent firmware package, not a bug in hardware detection.

Package is installed but driver still fails. Verify the expected image files, driver manual, attach timing, module version, and kernel messages. Schedule a controlled reload or reboot only if needed. Installing firmware cannot add support for an unsupported chipset or fix every driver defect.

Device disappears during activation. Use the management console or redundant path, retain a working kernel/module fallback, and capture the hardware and dmesg evidence. Do not repeatedly detach or reset the device without a diagnosis; a storage or network device can affect services beyond the one visible interface.

Operational acceptance

An accepted fwget workflow records FreeBSD release, hardware identifiers, driver, firmware requirement source, dry-run output, repository, installed package names, activation action, and post-change test. The device must attach without the relevant missing-firmware error and pass a function-specific validation such as network traffic or storage access.

Keep package installation separate from device firmware flashing and from driver support certification. fwget can shorten the discovery path for supported PCI and USB hardware, but it does not make every device compatible or prove correct operation. Report exactly which layer succeeded: detection, package installation, driver firmware load, device initialization, and application traffic.

Related:

Sources: