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) Submitting devicetree (DT) binding patches
^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. For patch submitters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) =======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)   0) Normal patch submission rules from Documentation/process/submitting-patches.rst
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)      applies.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)   1) The Documentation/ and include/dt-bindings/ portion of the patch should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)      be a separate patch. The preferred subject prefix for binding patches is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)        "dt-bindings: <binding dir>: ..."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)      The 80 characters of the subject are precious. It is recommended to not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)      use "Documentation" or "doc" because that is implied. All bindings are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)      docs. Repeating "binding" again should also be avoided.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)   2) DT binding files are written in DT schema format using json-schema
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)      vocabulary and YAML file format. The DT binding files must pass validation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)      by running::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)        make dt_binding_check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)      See ../writing-schema.rst for more details about schema and tools setup.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)   3) DT binding files should be dual licensed. The preferred license tag is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)      (GPL-2.0-only OR BSD-2-Clause).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)   4) Submit the entire series to the devicetree mailinglist at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)        devicetree@vger.kernel.org
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)      and Cc: the DT maintainers. Use scripts/get_maintainer.pl to identify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)      all of the DT maintainers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)   5) The Documentation/ portion of the patch should come in the series before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)      the code implementing the binding.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)   6) Any compatible strings used in a chip or board DTS file must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)      previously documented in the corresponding DT binding text file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)      in Documentation/devicetree/bindings.  This rule applies even if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)      the Linux device driver does not yet match on the compatible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)      string.  [ checkpatch will emit warnings if this step is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)      followed as of commit bff5da4335256513497cc8c79f9a9d1665e09864
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)      ("checkpatch: add DT compatible string documentation checks"). ]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)   7) The wildcard "<chip>" may be used in compatible strings, as in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)      the following example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)          - compatible: Must contain '"nvidia,<chip>-pcie",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)            "nvidia,tegra20-pcie"' where <chip> is tegra30, tegra132, ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)      As in the above example, the known values of "<chip>" should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)      documented if it is used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)   8) If a documented compatible string is not yet matched by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)      driver, the documentation should also include a compatible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)      string that is matched by the driver (as in the "nvidia,tegra20-pcie"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)      example above).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) II. For kernel maintainers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)   1) If you aren't comfortable reviewing a given binding, reply to it and ask
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)      the devicetree maintainers for guidance.  This will help them prioritize
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)      which ones to review and which ones are ok to let go.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)   2) For driver (not subsystem) bindings: If you are comfortable with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)      binding, and it hasn't received an Acked-by from the devicetree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)      maintainers after a few weeks, go ahead and take it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)      Subsystem bindings (anything affecting more than a single device)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)      then getting a devicetree maintainer to review it is required.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)   3) For a series going though multiple trees, the binding patch should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)      kept with the driver using the binding.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) III. Notes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)   0) Please see ...bindings/ABI.txt for details regarding devicetree ABI.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)   1) This document is intended as a general familiarization with the process as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)      decided at the 2013 Kernel Summit.  When in doubt, the current word of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)      devicetree maintainers overrules this document.  In that situation, a patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)      updating this document would be appreciated.