Write drivers
Porting a driver to new hardware
On this page
A plan for bringing a device that has no macOS driver to macOS, by porting an existing open-source driver from Linux or a BSD. It is written around network chips, where most hackintosh porting happens, but the stages apply to audio, input, storage and other devices too.
Expect a large job. The Intel Wi-Fi work this guide comes from stands on years of OpenIntelWireless effort: a complete 802.11 stack port and a working driver for the chip before any macOS-specific feature was attempted. For a device with no macOS driver at all, getting the basics working is a project in itself.
Read the legal boundaries before you start. They decide what you may look at, what you may commit, and which source drivers you may build on.
The layers
Most ported drivers end up with the same shape:
macOS family (IOKit) <-> glue <-> protocol stack <-> hardware layer <-> firmware
- The macOS family is Apple's framework for the device class (IO80211Family, IOAudioFamily, IOHIDFamily, IONetworkingFamily). You subclass its classes; you don't change them.
- The glue translates between that family and the rest of your driver.
- The protocol stack is often a port of a BSD stack (net80211 for Wi-Fi in itlwm).
- The hardware layer is the only part that is specific to one chip: registers, DMA rings, interrupts, firmware commands.
If a driver for a related chip already exists for macOS, you may only need a new hardware layer. That is how itlwm supports several Intel generations with one stack.
Step 1. Pick a source driver
Look for an existing open-source driver and check its license before reading any code.
| Source | Typical licenses | Notes |
|---|---|---|
| OpenBSD, FreeBSD, NetBSD | ISC, BSD-2/3-Clause | Closest to macOS in structure; itlwm's Wi-Fi stack is OpenBSD net80211, so a BSD Wi-Fi driver needs much less translation |
| Linux | GPL-2.0, sometimes dual GPL-2.0 OR BSD-3-Clause, ISC for some vendors | Widest hardware support and newest features; GPL code makes your kext GPL too |
| Vendor reference code | Varies | Read the terms; some forbid redistribution or other platforms |
Some examples for Wi-Fi: Linux rtw89 for recent Realtek chips (GPL-2.0 OR BSD-3-Clause), OpenBSD rtwn(4) for older Realtek chips (ISC, and already speaks net80211), Linux mt76 for MediaTek MT7921/MT7922 (mostly ISC), Linux ath10k and OpenBSD qwx(4) for Qualcomm Atheros.
Check the firmware too. Firmware files in linux-firmware come with their own redistribution terms. Include each firmware license file next to the firmware you bundle.
Step 2. Basic function first
Get the device doing its main job before anything macOS-specific:
- Fork the closest existing macOS driver, or start from a skeleton built on MacKernelSDK.
- Implement the hardware layer: probe and attach, firmware loading, interrupts, DMA rings, power management. If the project already has a hardware-layer interface (itlwm's
ItlHalServiceis one), implement that, and read an existing implementation top to bottom first. - Add the device IDs to the
Info.plistpersonalities. - Start with the simplest macOS interface that exercises the hardware. For Wi-Fi that means the Ethernet-style
itlwmtarget before the nativeAirportItlwmone. - Pass the usual tests for the device class. For Wi-Fi: scan, WPA2 and WPA3 association, sleep and wake, a day of traffic.
Expect weeks here: DMA, interrupts, power states, rate control and crypto offload all take time. Use boot-args to enable features one at a time, boot with keepsyms=1 debug=0x100, and check struct layouts after every build (see Keep the build honest).
Step 3. Check what the hardware can do before adding features
Before you implement a macOS feature on top, list what it needs from the hardware and check each need in the source driver and its firmware interface. That saves months spent on a feature the chip can't support.
AWDL (the link behind AirDrop) is a good example. It needs:
| Need | Why | Where to look in a Linux Wi-Fi driver |
|---|---|---|
| Off-channel dwells while associated, with a precise start notification | AWDL slots move between channels while the normal link stays up | remain_on_channel ops, firmware events for dwell start and end |
| A second MAC address the chip acknowledges | Peers send unicast to the AWDL interface's own address | P2P-device or multi-interface support |
| Receiving frames for a foreign BSSID | AWDL frames use their own BSSID | Per-interface RX filter control |
| Raw management and data frame TX on a chosen channel, with TX status | Discovery frames and AirDrop data | mgmt_tx, per-frame TX descriptors |
| Observable TX timing and a reliable clock | Frames must leave inside the peer's slot | TSF reads, dwell state, precise RX timestamps |
If the chip has P2P-device, remain-on-channel and management TX in Linux, it can almost certainly do AWDL with the AX210 project's design. The Wi-Fi porting plan in that project maps each callback to the Intel implementation and to the equivalent in Realtek rtw89.
Step 4. Bring features up in stages
- Start receive-only. When the device sees what it should see, add transmit, then data.
- Put each stage behind its own boot-arg, default off.
- Fill counters from the start and publish them in the IORegistry. They are how you will find every problem later.
Step 5. Measure, then tune
Measurements are what made AirDrop work on the AX210. Its firmware started off-channel dwells 10 to 75 ms late half of the time, which only showed up in a histogram, and led to the fix. Your hardware will have its own quirks. Record a session, compare a success with a failure, and fix the biggest difference first. The project's test results show what that process looks like.
Companion devices
Some features need more than one device. AirDrop discovery also needs Bluetooth LE advertising sets: a combo card's Bluetooth half has to be a controller macOS accepts (often after a firmware-loader kext), and it needs LE extended advertising (Bluetooth 5.0 or newer). Check the whole chain before you start.
Share what you have
If you get anywhere, even only to "the device probes", publish it and open a discussion with the upstream project. Partial ports are how the next person starts. When you have a release, submit it to the catalog and ask people to report tests.
Adapted from Porting native Wi-Fi and AWDL to other Wi-Fi chips in the AX210 AirDrop/AWDL project, by its contributors, MIT license.
Edit this page on GitHub. Something wrong or unclear? Open an issue or a pull request.