Introduction

Since 2015, I've been working on improving FreeBSD support for Broadcom Wi-Fi devices and SoCs, including authoring the bhnd(4) driver family, which provides a unified bus and driver programming interface for these devices.

First committed in early 2016, bhnd(4) allowed us to quickly bring up FreeBSD/MIPS on Broadcom SoCs, but it has taken much longer to implement the full set of features required to support modern Broadcom SoftMAC Wi-Fi hardware.

Thanks to the generosity of the FreeBSD Foundation, I've recently finished implementing the necessary improvements to the bhnd(4) driver family. With these changes in place, I was finally able to port the existing bwn(4) Broadcom SoftMAC Wi-Fi driver to the bhnd(4) bus, and implement initial support for the BCM43224 and BCM43225 chipsets, with additional hardware support to be forthcoming.

Now that my efforts on FreeBSD/Broadcom Wi-Fi support have progressed far enough to be generally useful, I wanted to take some time to provide a brief overview of Broadcom's Wi-Fi hardware, and explain how my work provides a foundation for further FreeBSD Broadcom Wi-Fi/SoC improvements.

A Brief Background on Broadcom Wi-Fi Hardware

Broadcom's Wi-Fi devices are members of the Broadcom Home Networking Division (BHND) device family; other BHND devices include MIPS/ARM SoCs (including Wi-Fi SoCs commonly found in consumer access points), as well as a large variety of related networking hardware.

BHND devices utilize a common set of Broadcom IP cores (or "functional blocks") connected via one of two on-chip bus architectures:

Hardware designed prior to 2009 used Broadcom’s “SSB” backplane architecture, based on Sonics Silicon’s interconnect IP.

Subsequent hardware adopted Broadcom’s “BCMA” backplane, based on ARM’s AMBA IP. The IP cores used in earlier SSB-based devices were adapted for compatibility with the new backplane.

When BHND hardware is used in a PCI Wi-Fi card, or a SDIO Wi-Fi module, the device's dual-mode peripheral controller is configured to operate as an endpoint device on the host's peripheral bus, bridging access to the SoC hardware:

Host access to SoC address space is provided via a set of register windows (e.g., a set of configurable windows into SoC address space mapped via PCI BARs)

DMA is supported by the bridge core’s sparse mapping of host address space into the backplane address space. These address regions may be used as a target for the on-chip DMA engines.

Any backplane interrupt vectors routed to the bridge core may be mapped by the bridge to host interrupts (e.g., PCI INTx/MSI/MSI-X).

The host is generally expected to provide drivers for the IP cores found on the SoC backplane; since these cores are found in both BHND SoCs and BHND Wi-Fi devices, it is advantageous to share driver and platform code between the two targets.

SoftMAC Hardware

Broadcom’s SoftMAC Wi-Fi chipsets contain a common “D11” MAC core, which provides runtime identification of — and a mostly media-independent interface to — Broadcom’s family of Wi-Fi PHY/RF chipsets.

The host driver is expected to implement most of the 802.11 MAC layer processing in software (hence "SoftMAC"), while the D11 core provides a simple programmable state machine (PSM) that manages low-level 802.11 hardware operations; the PSM's microcode must be provided at runtime by the host driver.

SoftMAC chipsets are found in PCI, PCIe, and CardBus Wi-Fi adapters, as well as pre-802.11ac WiSoCs.

FullMAC Hardware

Broadcom FullMAC Wi-Fi devices use the same D11 core as the SoftMAC devices, but also include an ARM CPU that's used to run Broadcom's HNDRTE embedded operating system. HNDRTE includes drivers for the D11 core, and is responsible for performing 802.11 MAC layer processing on the host's behalf (hence "FullMAC").

PCI(e) and SDIO FullMAC devices include only a minimal boot ROM; to bring up these devices, a host driver must enumerate the backplane-attached cores to locate the CPU, copy the ARM firmware into device memory, bring the CPU out of reset, and then communicate with the running ARM firmware via a shared block of device memory.

USB FullMAC devices operate similarly, but also include minimal USB bootloader. Rather than enumerating the bridged cores and copying the ARM firmware directly into device memory, the host driver uses the USB bootloader's high-level command protocol to transfer the ARM 802.11 FullMAC firmware to the device, and then request that the ARM core execute the new firmware. Once the ARM firmware is running, the host communicates with the firmware using USB control transfers.

A common FullMAC host driver may support USB, PCI, and SDIO FullMAC devices by implementing an abstraction layer for the bus-specific mechanism used to load and exchange messages with HNDRTE.

FullMAC chipsets are found in PCIe, SDIO, and USB/HSIC Wi-Fi adapters, as well as 802.11ac WiSoCs.

Note: Support for FullMAC hardware was not the focus of my initial work on bhnd(9) ; I've included this description for completeness.

(Wi)SoC Hardware

Broadcom SoCs are commonly found in both consumer and enterprise Wi-Fi access points, and may include a directly-attached D11 core, a PCI(e), USB, or SDIO FullMAC chipset, and/or combination of the same.

Prior to the adoption of 802.11ac, BHND Wi-Fi SoCs usually rely on a D11 core directly attached to the SoC backplane; these are effectively SoftMAC devices, with the embedded operating system (usually Linux) responsible 802.11 MAC layer processing.

In 802.11ac BHND WiSoCs, Wi-Fi support is usually provided by one or more FullMAC Wi-Fi devices, possibly on the same chip, attached via PCIe, SDIO, and/or USB/HSIC.

Modernizing FreeBSD's Broadcom SoftMAC Wi-Fi Support

FreeBSD support for Broadcom SoftMAC Wi-Fi adapters is provided by two partially overlapping PCI/CardBus drivers:

Legacy Wi-Fi adapters are supported by bwi(4) . This driver remains in-tree to support devices incompatible with v4 or later firmware (e.g. BCM4301, BCM4302, BCM4306 rev 1-2), all of which were released prior to December 2002.

. This driver remains in-tree to support devices incompatible with v4 or later firmware (e.g. BCM4301, BCM4302, BCM4306 rev 1-2), all of which were released prior to December 2002. Modern Wi-Fi adapters are supported by bwn(4) , with access to on-chip cores mediated by bhnd(4) .

Prior to my work porting bwn(4) to bhnd(4) , access to on-chip cores was mediated by siba_bwn , a PCI/WiFi-specific derivative of the legacy siba(4) SSB bus driver. There were two major limitations to siba_bwn that have long blocked adding support for newer SoftMAC Wi-Fi chipsets: the newer BCMA interconnect found in post-2009 hardware was not supported by siba(4) , and siba_bwn assumed a PCI/PCIe bridge, preventing its use on FreeBSD/MIPS Broadcom SoCs with interconnect-attached D11 cores.

The new bhnd(4) driver family, written as a replacement for siba(4) and siba_bwn , provides:

A unified bus driver interface for both SSB and BCMA on-chip interconnects

A generic BHND bridge driver framework for host-connected BHND devices (e.g. Wi-Fi adapters, etc)

A PCI/PCIe bridge core driver, for PCI-attached BHND devices.

An abstract BHND NVRAM API, with support for the varied NVRAM formats found in BHND Wi-Fi adapters and SoCs.

Drivers for common BHND platform peripherals (UARTs, SPROM/flash, PMUs, etc)

By porting bwn(4) to bhnd(4) , we are now able to support existing BCMA devices with MAC/PHY/Radio combinations readily supported by bwn(4), as was the case with the BCM43224 and BCM43225 chipsets. This also opens the door to porting additional PHY support from Broadcom’s ISC-licensed Linux drivers, and will allow us to bring up bwn(4) on Broadcom WiSoCs supported by FreeBSD/MIPS.

Frequently Asked Questions

Does this work mean my laptop's Broadcom wireless is supported now?

Maybe (and only if it's a SoftMAC chipset — refer to the table below).

I've enabled basic support for the BCM43224/BCM43225 chipsets using bwn(4) ’s optional, GPL-licensed PHY-N driver; the BCM43224 is found in many Macs released between 2009–2012.

Additional work will be necessary to bring up support for more modern Broadcom Wi-Fi SoftMAC chipsets; in particular, we will need to extend bwn(4) with support for more recent PHYs.

What about running FreeBSD/pfSense/etc on Broadcom’s Wi-Fi Access Points?

We're very close, but not quite there yet.

MIPS SoCs using a SoftMAC chipset will require a number small improvements to bhnd(4) , including extending the bhnd(9) NVRAM API to support querying device-specific properties. For full platform support, we’d also need to implement missing drivers for a number of onboard devices, including the PCI(e) host bridge core.

MIPS SoCs using a FullMAC chipset cannot be supported by bwn(4) , and will require implementing a new Broadcom FullMAC Wi-Fi driver.

ARM SoCs are not currently supported. These devices are BCMA based, and it should be possible to bring up a port using bhnd(4) , but no work on this has been done.

Will my laptop's wireless be supported in the future?

If your Wi-Fi chipset is a SoftMAC chipset supportable by bwn(4) , and uses a PHY supported by Broadcom’s brcmsmac Linux driver (see table below), then near-future support for your device is quite likely; since the brcmsmac driver implements an abstract PHY layer, we should be able to plug their ISC-licensed PHY code into bwn(4) .

Additionally, if any documentation or existing open-source drivers exist for your chipset’s PHY, support will largely depend on user/developer interest; for otherwise undocumented PHY hardware, considerably more expensive reverse engineering will be required before we can support the device.

What about 802.11ac Wi-Fi in my 2016 Retina MacBook Pro?

Broadcom FullMAC devices, including the BCM4350 found in the 2016 Retina MacBook Pro, cannot be supported by bwn(4) , and are not the focus of this work.

However, the bhnd(4) driver family may be leveraged as a porting target for Broadcom’s ISC-licensed brcmfmac Linux driver, as Broadcom’s SoftMAC and PCI/SDIO FullMAC Wi-Fi devices share a common bridged architecture, use the same SSB/BCMA interconnects, and share common platform cores.

Such a port of brcmfmac would provide FreeBSD support for the BCM4350, along with a number of other PCIe and USB FullMAC devices (for SDIO device support, refer to the next answer).

Alternatively, OpenBSD and NetBSD have both recently begun work to support Broadcom's FullMAC chipsets, and it may be possible to port their work as-is.

Note: All Broadcom SDIO and USB Wi-Fi chipsets are FullMAC devices.

How about my Raspberry Pi 3?

SDIO chipsets — such as the Raspberry Pi 3’s BCM43438 — are supported by brcmfmac, but will first require implementing SDIO support for FreeBSD (see D12467).