1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 =================== 3 ===================
4 Devicetree (DT) ABI 4 Devicetree (DT) ABI
5 =================== 5 ===================
6 6
7 I. Regarding stable bindings/ABI, we quote fro 7 I. Regarding stable bindings/ABI, we quote from the 2013 ARM mini-summit
8 summary document: 8 summary document:
9 9
10 "That still leaves the question of, what 10 "That still leaves the question of, what does a stable binding look
11 like? Certainly a stable binding means t 11 like? Certainly a stable binding means that a newer kernel will not
12 break on an older device tree, but that d 12 break on an older device tree, but that doesn't mean the binding is
13 frozen for all time. Grant said there are 13 frozen for all time. Grant said there are ways to change bindings that
14 don't result in breakage. For instance, i 14 don't result in breakage. For instance, if a new property is added,
15 then default to the previous behaviour if 15 then default to the previous behaviour if it is missing. If a binding
16 truly needs an incompatible change, then 16 truly needs an incompatible change, then change the compatible string
17 at the same time. The driver can bind ag 17 at the same time. The driver can bind against both the old and the
18 new. These guidelines aren't new, but the 18 new. These guidelines aren't new, but they desperately need to be
19 documented." 19 documented."
20 20
21 II. General binding rules 21 II. General binding rules
22 22
23 1) Maintainers, don't let perfect be the ene 23 1) Maintainers, don't let perfect be the enemy of good. Don't hold up a
24 binding because it isn't perfect. 24 binding because it isn't perfect.
25 25
26 2) Use specific compatible strings so that i 26 2) Use specific compatible strings so that if we need to add a feature (DMA)
27 in the future, we can create a new compat 27 in the future, we can create a new compatible string. See I.
28 28
29 3) Bindings can be augmented, but the driver 29 3) Bindings can be augmented, but the driver shouldn't break when given
30 the old binding. ie. add additional prope 30 the old binding. ie. add additional properties, but don't change the
31 meaning of an existing property. For driv 31 meaning of an existing property. For drivers, default to the original
32 behaviour when a newly added property is 32 behaviour when a newly added property is missing.
33 33
34 4) Don't submit bindings for staging or unst 34 4) Don't submit bindings for staging or unstable. That will be decided by
35 the devicetree maintainers *after* discus 35 the devicetree maintainers *after* discussion on the mailinglist.
36 36
37 III. Notes 37 III. Notes
38 38
39 1) This document is intended as a general fa 39 1) This document is intended as a general familiarization with the process as
40 decided at the 2013 Kernel Summit. When 40 decided at the 2013 Kernel Summit. When in doubt, the current word of the
41 devicetree maintainers overrules this doc 41 devicetree maintainers overrules this document. In that situation, a patch
42 updating this document would be appreciat 42 updating this document would be appreciated.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.