diff options
author | Mauro Carvalho Chehab <mchehab+huawei@kernel.org> | 2020-04-15 17:45:24 +0300 |
---|---|---|
committer | Rob Herring <robh@kernel.org> | 2020-05-05 01:09:52 +0300 |
commit | 56516a9fe1058c15af2de98418758c6c30f3cdf1 (patch) | |
tree | bfd04cfc7262bd09494259b7662cc1f78b7779bd /Documentation/devicetree/bindings/ABI.rst | |
parent | 642e6e5ce03e5b02d658e87d6c21d881b1ce8f62 (diff) | |
download | linux-56516a9fe1058c15af2de98418758c6c30f3cdf1.tar.xz |
docs: dt: convert ABI.txt to ReST format
This file only requires a properly-formatted title to be
recognized as a ReST file.
As there will be more files under bindings/ that will be
included at the documentation body, add a new index.rst
file there.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
Diffstat (limited to 'Documentation/devicetree/bindings/ABI.rst')
-rw-r--r-- | Documentation/devicetree/bindings/ABI.rst | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/Documentation/devicetree/bindings/ABI.rst b/Documentation/devicetree/bindings/ABI.rst new file mode 100644 index 000000000000..a885713cf184 --- /dev/null +++ b/Documentation/devicetree/bindings/ABI.rst @@ -0,0 +1,42 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================== +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. |