Using AI to Port a Wi-Fi Driver from Linux to FreeBSD: A Case Study

Direct AI Code Porting Attempt

The developer had a 2016 MacBook Pro with a Broadcom BCM4350 Wi-Fi chip that lacks native FreeBSD support. The typical workaround is wifibox - a Linux VM with PCI pass-through. Instead, they attempted to port the Linux brcmfmac driver (ISC license) directly to FreeBSD using AI.

They cloned the brcmfmac subtree and asked Claude Code to make it work for FreeBSD, specifically pointing to the iwlwifi driver as a reference for using LinuxKPI (FreeBSD's Linux kernel compatibility layer). The initial attempt produced a module that compiled but didn't function because the test VM lacked the actual hardware.

When testing with the actual PCI device, the kernel panicked. Claude Code attempted to fix panics by adding #ifdef __FreeBSD__ wrappers and building FreeBSD-specific shims and callbacks, but warned the project was becoming "very complicated and messy." The resulting diff was significantly larger than expected, and the driver remained non-functional.

Specification-First Approach

Inspired by Armin Ronacher's experience with Claude Opus and Pi agent, the developer switched approaches. Recognizing their task was narrow (one chip, only PCI, only Wi-Fi client), they spawned a fresh Pi session and asked the agent to write a detailed specification of how the brcmfmac driver works with focus on BCM4350.

They explicitly set the audience as "readers tasked with implementing the specification in a clean-room environment" and asked for explanations "to the bits." The agent produced an 11-chapter specification covering:

• 00-overview.md
• 01-data-structures.md
• 02-bus-layer.md
• 03-protocol-layer.md
• 04-firmware-interface.md
• 05-event-handling.md
• 06-cfg80211-operations.md
• 07-initialization.md
• 08-data-path.md
• 09-firmware-commands.md
• 10-structures-reference.md

The developer notes that AI-generated specifications require verification, as one "can't just trust what AI has written."