Write drivers

Porting a driver to new hardware

5 min read

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.

SourceTypical licensesNotes
OpenBSD, FreeBSD, NetBSDISC, BSD-2/3-ClauseClosest to macOS in structure; itlwm's Wi-Fi stack is OpenBSD net80211, so a BSD Wi-Fi driver needs much less translation
LinuxGPL-2.0, sometimes dual GPL-2.0 OR BSD-3-Clause, ISC for some vendorsWidest hardware support and newest features; GPL code makes your kext GPL too
Vendor reference codeVariesRead 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:

  1. Fork the closest existing macOS driver, or start from a skeleton built on MacKernelSDK.
  2. 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 ItlHalService is one), implement that, and read an existing implementation top to bottom first.
  3. Add the device IDs to the Info.plist personalities.
  4. Start with the simplest macOS interface that exercises the hardware. For Wi-Fi that means the Ethernet-style itlwm target before the native AirportItlwm one.
  5. 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:

NeedWhyWhere to look in a Linux Wi-Fi driver
Off-channel dwells while associated, with a precise start notificationAWDL slots move between channels while the normal link stays upremain_on_channel ops, firmware events for dwell start and end
A second MAC address the chip acknowledgesPeers send unicast to the AWDL interface's own addressP2P-device or multi-interface support
Receiving frames for a foreign BSSIDAWDL frames use their own BSSIDPer-interface RX filter control
Raw management and data frame TX on a chosen channel, with TX statusDiscovery frames and AirDrop datamgmt_tx, per-frame TX descriptors
Observable TX timing and a reliable clockFrames must leave inside the peer's slotTSF 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.