Orange Pi5 kernel

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