Upstreaming a Driver to the Linux Kernel: Why and How
The Linux kernel has no stable internal API. Internal interfaces change whenever a better design is found, and whoever changes them updates every in-tree driver. A driver kept outside the tree gets no such help: each new kernel can break the build or, worse, change behaviour silently. Upstreaming means getting the driver accepted into the mainline kernel, so it is built, tested and updated along with everything else.
At a glance
- Mainline
- The main kernel tree, with a new release roughly every nine to ten weeks.
- 2 weeks
- The merge window after each release, when new features and drivers are pulled in.
- checkpatch
- The kernel script that checks patches for style problems and common mistakes.
- Signed-off
- Every patch carries a Signed-off-by line certifying the Developer Certificate of Origin.
The problem
Out-of-tree drivers age quickly. A product moving to a newer kernel for security fixes faces a port of every private driver, often by engineers who did not write them. Distributions will not carry the driver, so customers who build their own kernels must patch it in themselves.
Teams also put off upstreaming because the process looks opaque: patches by email, public review, several revisions. Submissions sent without preparation tend to stall, which reinforces the impression.
Upstreaming costs effort once; staying out of tree costs effort with every kernel release for as long as the product is supported.
What reviewers look for
Maintainers expect a driver to use existing frameworks rather than invent interfaces, to follow kernel coding style, and to arrive as a logical series: the device tree binding first, then the driver, then any board changes. Bindings are reviewed by the device tree maintainers and must pass schema validation. Each patch needs a commit message explaining what it does and why, and the code must build without new warnings.
Use the get_maintainer script to find the right maintainers and mailing lists, send plain-text patches with git send-email or the b4 tool, and answer review comments on the list. Accepted patches go into the subsystem tree, appear in linux-next for wider testing, and reach mainline in the next merge window.
What good looks like
Rebase onto current mainline and its frameworks, then run checkpatch and the binding checks.
Split the work into a reviewable series with clear commit messages, and send it to the people and lists the get_maintainer script names.
Respond to every review comment, post revised versions promptly, and keep the series rebased until a maintainer applies it.
Path of a driver into mainline
- Prepare: Rebase, checkpatch, binding checks
- Post: Series to maintainers and lists
- Review: Revisions until accepted
- Subsystem tree: Applied, then tested in linux-next
- Mainline: Pulled in the merge window
| Out of tree | Upstream | |
|---|---|---|
| Effort to start | Lower | Higher: review and rework |
| Effort per kernel release | Port and retest each time | Largely shared with the community |
| Availability to customers | Only from you | In standard kernels |
| Control over timing | Ship whenever ready | Follows the release cycle |
| Code review | Internal only | Subsystem experts |
What it changes
Lower Maintenance
Internal API changes are carried into your driver by the developers who make them.
Wider Reach
Distributions and downstream kernels include the driver without extra work.
Better Code
Public review by subsystem experts finds problems internal review misses.
Customer Confidence
A mainline driver is easier for customers to audit, build and support.
Where to go next
Upstream early: a driver merged before launch is in the kernels customers will run.
For Android products, Google encourages an upstream-first approach, which also eases the move to newer GKI kernels.
Problems this prevents
- A private driver to port for every kernel update
- Patches ignored because they went to the wrong list
- Review stalled by a missing device tree binding
- Interfaces rejected for duplicating a subsystem
Discuss your project
Email support@aavico.com or use Get in Touch when the website finishes loading.