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