dt/bindings: submitting patches and ABI documents

Add some guidance documentation about what to do with device tree
bindings and how ABI stability is to be handled.

Signed-off-by: Jason Cooper <jason@lakedaemon.net>
[grant.likely: added some clarification on subsystem binding rules]
Signed-off-by: Grant Likely <grant.likely@linaro.org>

2 files changed, 77 insertions, 0 deletions

diff --git a/Documentation/devicetree/bindings/ABI.txt b/Documentation/devicetree/bindings/ABI.txt
new file mode 100644
index 000000000000..d25f8d379680
--- /dev/null
+++ b/Documentation/devicetree/bindings/ABI.txt
@@ -0,0 +1,39 @@
+
+  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/submitting-patches.txt b/Documentation/devicetree/bindings/submitting-patches.txt
new file mode 100644
index 000000000000..042a0273b8ba
--- /dev/null
+++ b/Documentation/devicetree/bindings/submitting-patches.txt
@@ -0,0 +1,38 @@
+
+  Submitting devicetree (DT) binding patches
+
+I. For patch submitters
+
+  0) Normal patch submission rules from Documentation/SubmittingPatches
+     applies.
+
+  1) The Documentation/ portion of the patch should be a separate patch.
+
+  2) Submit the entire series to the devicetree mailinglist at
+
+       devicetree@vger.kernel.org
+
+II. For kernel maintainers
+
+  1) If you aren't comfortable reviewing a given binding, reply to it and ask
+     the devicetree maintainers for guidance.  This will help them prioritize
+     which ones to review and which ones are ok to let go.
+
+  2) For driver (not subsystem) bindings: If you are comfortable with the
+     binding, and it hasn't received an Acked-by from the devicetree
+     maintainers after a few weeks, go ahead and take it.
+
+     Subsystem bindings (anything affecting more than a single device)
+     then getting a devicetree maintainer to review it is required.
+
+  3) For a series going though multiple trees, the binding patch should be
+     kept with the driver using the binding.
+
+III. Notes
+
+  0) Please see ...bindings/ABI.txt for details regarding devicetree ABI.
+
+  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.