0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===================
0004 Devicetree (DT) ABI
0005 ===================
0006
0007 I. Regarding stable bindings/ABI, we quote from the 2013 ARM mini-summit
0008 summary document:
0009
0010 "That still leaves the question of, what does a stable binding look
0011 like? Certainly a stable binding means that a newer kernel will not
0012 break on an older device tree, but that doesn't mean the binding is
0013 frozen for all time. Grant said there are ways to change bindings that
0014 don't result in breakage. For instance, if a new property is added,
0015 then default to the previous behaviour if it is missing. If a binding
0016 truly needs an incompatible change, then change the compatible string
0017 at the same time. The driver can bind against both the old and the
0018 new. These guidelines aren't new, but they desperately need to be
0019 documented."
0020
0021 II. General binding rules
0022
0023 1) Maintainers, don't let perfect be the enemy of good. Don't hold up a
0024 binding because it isn't perfect.
0025
0026 2) Use specific compatible strings so that if we need to add a feature (DMA)
0027 in the future, we can create a new compatible string. See I.
0028
0029 3) Bindings can be augmented, but the driver shouldn't break when given
0030 the old binding. ie. add additional properties, but don't change the
0031 meaning of an existing property. For drivers, default to the original
0032 behaviour when a newly added property is missing.
0033
0034 4) Don't submit bindings for staging or unstable. That will be decided by
0035 the devicetree maintainers *after* discussion on the mailinglist.
0036
0037 III. Notes
0038
0039 1) This document is intended as a general familiarization with the process as
0040 decided at the 2013 Kernel Summit. When in doubt, the current word of the
0041 devicetree maintainers overrules this document. In that situation, a patch
0042 updating this document would be appreciated.
