From 56516a9fe1058c15af2de98418758c6c30f3cdf1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 15 Apr 2020 16:45:24 +0200 Subject: 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 --- Documentation/arm/microchip.rst | 2 +- Documentation/devicetree/bindings/ABI.rst | 42 ++++++++++++++++++++++ Documentation/devicetree/bindings/ABI.txt | 39 -------------------- Documentation/devicetree/bindings/arm/amlogic.yaml | 2 +- Documentation/devicetree/bindings/arm/syna.txt | 2 +- Documentation/devicetree/bindings/index.rst | 10 ++++++ Documentation/devicetree/index.rst | 2 ++ 7 files changed, 57 insertions(+), 42 deletions(-) create mode 100644 Documentation/devicetree/bindings/ABI.rst delete mode 100644 Documentation/devicetree/bindings/ABI.txt create mode 100644 Documentation/devicetree/bindings/index.rst diff --git a/Documentation/arm/microchip.rst b/Documentation/arm/microchip.rst index 05e5f2dfb814..9c013299fd3b 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 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. diff --git a/Documentation/devicetree/bindings/ABI.txt b/Documentation/devicetree/bindings/ABI.txt deleted file mode 100644 index d25f8d379680..000000000000 --- 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 f74aba48cec1..a21ce4ad63f6 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 2face46a5f64..d8b48f2edf1b 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 000000000000..98ebdab24b51 --- /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 1c36bc19969b..54026763916d 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 -- cgit v1.2.3-59-g8ed1b