Devicetree (DT) ABI

  1. Regarding stable bindings/ABI, we quote from the 2013 ARM mini-summitsummary document:

    “That still leaves the question of, what does a stable binding looklike? Certainly a stable binding means that a newer kernel will notbreak on an older device tree, but that doesn’t mean the binding isfrozen for all time. Grant said there are ways to change bindings thatdon’t result in breakage. For instance, if a new property is added,then default to the previous behaviour if it is missing. If a bindingtruly needs an incompatible change, then change the compatible stringat the same time. The driver can bind against both the old and thenew. These guidelines aren’t new, but they desperately need to bedocumented.”

  2. General binding rules

  1. Maintainers, don’t let perfect be the enemy of good. Don’t hold up abinding 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 giventhe old binding. ie. add additional properties, but don’t change themeaning of an existing property. For drivers, default to the originalbehaviour when a newly added property is missing.

  4. Don’t submit bindings for staging or unstable. That will be decided bythe devicetree maintainersafter discussion on the mailinglist.

  1. Notes

  1. This document is intended as a general familiarization with the process asdecided at the 2013 Kernel Summit. When in doubt, the current word of thedevicetree maintainers overrules this document. In that situation, a patchupdating this document would be appreciated.