Commit 2a933001 authored by Jason Cooper's avatar Jason Cooper Committed by Grant Likely

dt/bindings: submitting patches and ABI documents

Add some guidance documentation about what to do with device tree
bindings and how ABI stability is to be handled.
Signed-off-by: default avatarJason Cooper <jason@lakedaemon.net>
[grant.likely: added some clarification on subsystem binding rules]
Signed-off-by: default avatarGrant Likely <grant.likely@linaro.org>
parent 42ccd781
Devicetree (DT) ABI
I. Regarding stable bindings/ABI, we quote from the 2013 ARM mini-summit
summary document:
"That still leaves the question of, what does a stable binding look
like? Certainly a stable binding means that a newer kernel will not
break on an older device tree, but that doesn't mean the binding is
frozen for all time. Grant said there are ways to change bindings that
don't result in breakage. For instance, if a new property is added,
then default to the previous behaviour if it is missing. If a binding
truly needs an incompatible change, then change the compatible string
at the same time. The driver can bind against both the old and the
new. These guidelines aren't new, but they desperately need to be
documented."
II. General binding rules
1) Maintainers, don't let perfect be the enemy of good. Don't hold up a
binding because it isn't perfect.
2) Use specific compatible strings so that if we need to add a feature (DMA)
in the future, we can create a new compatible string. See I.
3) Bindings can be augmented, but the driver shouldn't break when given
the old binding. ie. add additional properties, but don't change the
meaning of an existing property. For drivers, default to the original
behaviour when a newly added property is missing.
4) Don't submit bindings for staging or unstable. That will be decided by
the devicetree maintainers *after* discussion on the mailinglist.
III. Notes
1) This document is intended as a general familiarization with the process as
decided at the 2013 Kernel Summit. When in doubt, the current word of the
devicetree maintainers overrules this document. In that situation, a patch
updating this document would be appreciated.
Submitting devicetree (DT) binding patches
I. For patch submitters
0) Normal patch submission rules from Documentation/SubmittingPatches
applies.
1) The Documentation/ portion of the patch should be a separate patch.
2) Submit the entire series to the devicetree mailinglist at
devicetree@vger.kernel.org
II. For kernel maintainers
1) If you aren't comfortable reviewing a given binding, reply to it and ask
the devicetree maintainers for guidance. This will help them prioritize
which ones to review and which ones are ok to let go.
2) For driver (not subsystem) bindings: If you are comfortable with the
binding, and it hasn't received an Acked-by from the devicetree
maintainers after a few weeks, go ahead and take it.
Subsystem bindings (anything affecting more than a single device)
then getting a devicetree maintainer to review it is required.
3) For a series going though multiple trees, the binding patch should be
kept with the driver using the binding.
III. Notes
0) Please see ...bindings/ABI.txt for details regarding devicetree ABI.
1) This document is intended as a general familiarization with the process as
decided at the 2013 Kernel Summit. When in doubt, the current word of the
devicetree maintainers overrules this document. In that situation, a patch
updating this document would be appreciated.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment