Documentation/devicetree/bindings/submitting-patches.rst

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