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