From: Mauro Carvalho Chehab Date: Wed, 15 Apr 2020 14:45:24 +0000 (+0200) Subject: docs: dt: convert ABI.txt to ReST format X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=56516a9fe1058c15af2de98418758c6c30f3cdf1;p=linux.git 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 Signed-off-by: Rob Herring --- diff --git a/Documentation/arm/microchip.rst b/Documentation/arm/microchip.rst index 05e5f2dfb814b..9c013299fd3bf 100644 --- a/Documentation/arm/microchip.rst +++ b/Documentation/arm/microchip.rst @@ -192,7 +192,7 @@ Device Tree files and Device Tree bindings that apply to AT91 SoCs and boards ar considered as "Unstable". To be completely clear, any at91 binding can change at any time. So, be sure to use a Device Tree Binary and a Kernel Image generated from the same source tree. -Please refer to the Documentation/devicetree/bindings/ABI.txt file for a +Please refer to the Documentation/devicetree/bindings/ABI.rst file for a definition of a "Stable" binding/ABI. This statement will be removed by AT91 MAINTAINERS when appropriate. diff --git a/Documentation/devicetree/bindings/ABI.rst b/Documentation/devicetree/bindings/ABI.rst new file mode 100644 index 0000000000000..a885713cf184b --- /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. diff --git a/Documentation/devicetree/bindings/ABI.txt b/Documentation/devicetree/bindings/ABI.txt deleted file mode 100644 index d25f8d3796806..0000000000000 --- a/Documentation/devicetree/bindings/ABI.txt +++ /dev/null @@ -1,39 +0,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. diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index f74aba48cec1b..a21ce4ad63f68 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -17,7 +17,7 @@ description: |+ any time. Be sure to use a device tree binary and a kernel image generated from the same source tree. - Please refer to Documentation/devicetree/bindings/ABI.txt for a definition of a + Please refer to Documentation/devicetree/bindings/ABI.rst for a definition of a stable binding/ABI. properties: diff --git a/Documentation/devicetree/bindings/arm/syna.txt b/Documentation/devicetree/bindings/arm/syna.txt index 2face46a5f64d..d8b48f2edf1b7 100644 --- a/Documentation/devicetree/bindings/arm/syna.txt +++ b/Documentation/devicetree/bindings/arm/syna.txt @@ -13,7 +13,7 @@ considered "unstable". Any Marvell Berlin device tree binding may change at any time. Be sure to use a device tree binary and a kernel image generated from the same source tree. -Please refer to Documentation/devicetree/bindings/ABI.txt for a definition of a +Please refer to Documentation/devicetree/bindings/ABI.rst for a definition of a stable binding/ABI. --------------------------------------------------------------- diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst new file mode 100644 index 0000000000000..98ebdab24b516 --- /dev/null +++ b/Documentation/devicetree/bindings/index.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========== +Device Tree +=========== + +.. toctree:: + :maxdepth: 1 + + ABI diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 1c36bc19969b0..54026763916d4 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -13,3 +13,5 @@ Open Firmware and Device Tree dynamic-resolution-notes of_unittest overlay-notes + + bindings/index