Porting device drivers between Linux and Windows: what actually changes

A network controller does not know which operating system is driving it. Its registers, its descriptor rings, its interrupt behaviour and its quirks are the same whether the code above them is a Linux net_device or a Windows NDIS miniport. That is the good news about porting a driver between the two, and it is why the first step of any port is to separate the code that knows about the hardware from the code that knows about the kernel.

The bad news is that everything else changes, and the changes are not cosmetic. The two kernels have different ideas about what a request is, when your code can sleep, how memory reaches a device, and how a driver gets from a build machine onto a user’s computer. Engineers who are expert on one side reliably fall into the same traps on the other. Here is the map we use, and the traps.

The side-by-side map

The traps, in the direction they usually catch people

Linux engineers arriving on Windows

• IRQL is not a suggestion. Touching paged memory or waiting on anything at DISPATCH_LEVEL does not fail gracefully; it produces a bug check, and only sometimes, depending on whether the page happened to be resident. Every function needs a known maximum IRQL, and the Driver Verifier option that forces paged memory out is mandatory during development.
• The ISR does almost nothing. Acknowledge the device, capture what must be captured, queue a DPC. Real work in the ISR blocks every interrupt at or below that DIRQL on that processor.
• Cancellation is your problem. A pending IRP can be cancelled at any time; the driver must either complete it promptly or register a cancel routine, and get the race between completion and cancellation right. KMDF removes most of this pain if you let it own the request queues.
• PnP and power states are a state machine you do not own. Surprise removal, stop-and-restart with new resources, and power transitions arrive as requests you must handle in order. Again, KMDF exists so that you implement callbacks instead of the state machine.
• There is no dma_map_single. DMA goes through an adapter object and, on 64-bit systems with 32-bit-capable devices, through map registers that bounce for you. Skipping the DMA API and handing a physical address to the device works on your test machine and corrupts memory on the one with an IOMMU.

Windows engineers arriving on Linux

• Atomic context is implicit. There is no IRQL to read; whether you may sleep depends on how you were called. might_sleep() and lockdep will tell you, but only at runtime and only on the path that was exercised.
• The subsystem owns the request model. There is no generic IRP; a network driver receives sk_buffs through the netdev API and a block driver receives requests from the block layer, with different rules for each. The subsystem’s expectations about locking and context are documented in its headers and in existing drivers, not in one place.
• Cache coherency is platform-dependent. On x86 the DMA API is nearly a no-op; on many ARM platforms dma_sync_* calls are what makes the data visible, and forgetting them produces bugs that never appear on the development PC. Windows’ DMA abstractions handle much of this under the covers; Linux expects the driver to call the API at the right moments.
• Upstream has opinions. A driver destined for the mainline kernel will be reviewed for style, for use of existing helpers instead of reimplementations, and for device-tree binding correctness. Budget for that review; it is where most of the schedule goes on a first upstream submission.
• There is no INF. Device binding is by ID tables in code or by device tree; user-visible configuration is sysfs or module parameters. Installers are a distribution’s business, not the driver’s.

How we structure a port

1. Extract the hardware layer first. Register definitions, ring management, command encoding, firmware loading and the device’s state machine become OS-independent C with a small interface: read and write registers, allocate DMA memory, log, delay. On the existing driver this is a refactor with the existing tests as a safety net.
2. Port the tests before the driver. Whatever exercised the hardware layer on the source OS (loopback tests, register self-tests, firmware load checks) is ported to run against the new OS’s glue first. It tells you that the DMA and interrupt plumbing works before the driver logic obscures the result.
3. Write the OS glue thin, and in the OS’s idiom. A KMDF driver that looks like a Linux driver wearing a costume will fight the framework at every power transition. Use the request queues, the DMA enabler and the power callbacks the way the samples do. The same holds in reverse: a Linux driver that reimplements a PnP state machine will be rejected upstream.
4. Verify with the OS’s verifier. Driver Verifier with the strict options on Windows; lockdep, KASAN and sparse on Linux. Both find the context and locking mistakes that the other OS would have let you make.
5. Document the mapping. A short table, like the one above but specific to this driver, of which source-side concept became which target-side construct. The next engineer will otherwise re-derive it.