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

  1. Prepare: Rebase, checkpatch, binding checks
  2. Post: Series to maintainers and lists
  3. Review: Revisions until accepted
  4. Subsystem tree: Applied, then tested in linux-next
  5. Mainline: Pulled in the merge window
Review usually takes several rounds; the time depends on the subsystem and the quality of the first posting.
Out-of-tree and upstream drivers
Out of treeUpstream
Effort to startLowerHigher: review and rework
Effort per kernel releasePort and retest each timeLargely shared with the community
Availability to customersOnly from youIn standard kernels
Control over timingShip whenever readyFollows the release cycle
Code reviewInternal onlySubsystem experts
Upstreaming front-loads the effort; staying out of tree spreads it over the product life.

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.