submitting-patches.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3==========================================
  4Submitting Devicetree (DT) binding patches
  5==========================================
  6
  7I. 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", "doc" or "YAML" because that is implied. All
 25     bindings are docs and all new bindings are supposed to be in Devicetree
 26     schema format.  Repeating "binding" again should also be avoided, so for
 27     a new device it is often enough for example::
 28
 29       "dt-bindings: iio: adc: Add ROHM BD79100G"
 30
 31     Conversion of other formats to DT schema::
 32
 33       "dt-bindings: iio: adc: adi,ad7476: Convert to DT schema"
 34
 35  2) DT binding files are written in DT schema format using json-schema
 36     vocabulary and YAML file format. The DT binding files must pass validation
 37     by running::
 38
 39       make dt_binding_check
 40
 41     See Documentation/devicetree/bindings/writing-schema.rst for more details
 42     about schema and tools setup.
 43
 44  3) DT binding files should be dual licensed. The preferred license tag is
 45     (GPL-2.0-only OR BSD-2-Clause).
 46
 47  4) Submit the entire series to the devicetree mailinglist at
 48
 49       devicetree@vger.kernel.org
 50
 51     and Cc: the DT maintainers. Use scripts/get_maintainer.pl to identify
 52     all of the DT maintainers.
 53
 54  5) The Documentation/ portion of the patch should come in the series before
 55     the code implementing the binding.
 56
 57  6) Any compatible strings used in a chip or board DTS file must be
 58     previously documented in the corresponding DT binding file
 59     in Documentation/devicetree/bindings.  This rule applies even if
 60     the Linux device driver does not yet match on the compatible
 61     string.  [ checkpatch will emit warnings if this step is not
 62     followed as of commit bff5da4335256513497cc8c79f9a9d1665e09864
 63     ("checkpatch: add DT compatible string documentation checks"). ]
 64
 65  7) DTS is treated in general as driver-independent hardware description, thus
 66     any DTS patches, regardless whether using existing or new bindings, should
 67     be placed at the end of patchset to indicate no dependency of drivers on
 68     the DTS.  DTS will be anyway applied through separate tree or branch, so
 69     different order would indicate the series is non-bisectable.
 70
 71     If a driver subsystem maintainer prefers to apply entire set, instead of
 72     their relevant portion of patchset, please split the DTS patches into
 73     separate patchset with a reference in changelog or cover letter to the
 74     bindings submission on the mailing list.
 75
 76  8) If a documented compatible string is not yet matched by the
 77     driver, the documentation should also include a compatible
 78     string that is matched by the driver.
 79
 80  9) Bindings are actively used by multiple projects other than the Linux
 81     Kernel, extra care and consideration may need to be taken when making changes
 82     to existing bindings.
 83
 84II. For kernel maintainers
 85==========================
 86
 87  1) If you aren't comfortable reviewing a given binding, reply to it and ask
 88     the devicetree maintainers for guidance.  This will help them prioritize
 89     which ones to review and which ones are ok to let go.
 90
 91  2) For driver (not subsystem) bindings: If you are comfortable with the
 92     binding, and it hasn't received an Acked-by from the devicetree
 93     maintainers after a few weeks, go ahead and take it.
 94
 95     For subsystem bindings (anything affecting more than a single device),
 96     getting a devicetree maintainer to review it is required.
 97
 98  3) For a series going through multiple trees, the binding patch should be
 99     kept with the driver using the binding.
100
101  4) The DTS files should however never be applied via driver subsystem tree,
102     but always via platform SoC trees on dedicated branches (see also
103     Documentation/process/maintainer-soc.rst).
104
105III. Notes
106==========
107
108  0) Please see Documentation/devicetree/bindings/ABI.rst for details
109     regarding devicetree ABI.
110
111  1) This document is intended as a general familiarization with the process as
112     decided at the 2013 Kernel Summit.  When in doubt, the current word of the
113     devicetree maintainers overrules this document.  In that situation, a patch
114     updating this document would be appreciated.