0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ==========================================
0004 Submitting Devicetree (DT) binding patches
0005 ==========================================
0006
0007 I. For patch submitters
0008 =======================
0009
0010 0) Normal patch submission rules from
0011 Documentation/process/submitting-patches.rst applies.
0012
0013 1) The Documentation/ and include/dt-bindings/ portion of the patch should
0014 be a separate patch. The preferred subject prefix for binding patches is::
0015
0016 "dt-bindings: <binding dir>: ..."
0017
0018 The 80 characters of the subject are precious. It is recommended to not
0019 use "Documentation" or "doc" because that is implied. All bindings are
0020 docs. Repeating "binding" again should also be avoided.
0021
0022 2) DT binding files are written in DT schema format using json-schema
0023 vocabulary and YAML file format. The DT binding files must pass validation
0024 by running::
0025
0026 make dt_binding_check
0027
0028 See Documentation/devicetree/bindings/writing-schema.rst for more details
0029 about schema and tools setup.
0030
0031 3) DT binding files should be dual licensed. The preferred license tag is
0032 (GPL-2.0-only OR BSD-2-Clause).
0033
0034 4) Submit the entire series to the devicetree mailinglist at
0035
0036 devicetree@vger.kernel.org
0037
0038 and Cc: the DT maintainers. Use scripts/get_maintainer.pl to identify
0039 all of the DT maintainers.
0040
0041 5) The Documentation/ portion of the patch should come in the series before
0042 the code implementing the binding.
0043
0044 6) Any compatible strings used in a chip or board DTS file must be
0045 previously documented in the corresponding DT binding text file
0046 in Documentation/devicetree/bindings. This rule applies even if
0047 the Linux device driver does not yet match on the compatible
0048 string. [ checkpatch will emit warnings if this step is not
0049 followed as of commit bff5da4335256513497cc8c79f9a9d1665e09864
0050 ("checkpatch: add DT compatible string documentation checks"). ]
0051
0052 7) The wildcard "<chip>" may be used in compatible strings, as in
0053 the following example:
0054
0055 - compatible: Must contain '"nvidia,<chip>-pcie",
0056 "nvidia,tegra20-pcie"' where <chip> is tegra30, tegra132, ...
0057
0058 As in the above example, the known values of "<chip>" should be
0059 documented if it is used.
0060
0061 8) If a documented compatible string is not yet matched by the
0062 driver, the documentation should also include a compatible
0063 string that is matched by the driver (as in the "nvidia,tegra20-pcie"
0064 example above).
0065
0066 9) Bindings are actively used by multiple projects other than the Linux
0067 Kernel, extra care and consideration may need to be taken when making changes
0068 to existing bindings.
0069
0070 II. For kernel maintainers
0071 ==========================
0072
0073 1) If you aren't comfortable reviewing a given binding, reply to it and ask
0074 the devicetree maintainers for guidance. This will help them prioritize
0075 which ones to review and which ones are ok to let go.
0076
0077 2) For driver (not subsystem) bindings: If you are comfortable with the
0078 binding, and it hasn't received an Acked-by from the devicetree
0079 maintainers after a few weeks, go ahead and take it.
0080
0081 For subsystem bindings (anything affecting more than a single device),
0082 getting a devicetree maintainer to review it is required.
0083
0084 3) For a series going though multiple trees, the binding patch should be
0085 kept with the driver using the binding.
0086
0087 III. Notes
0088 ==========
0089
0090 0) Please see Documentation/devicetree/bindings/ABI.rst for details
0091 regarding devicetree ABI.
0092
0093 1) This document is intended as a general familiarization with the process as
0094 decided at the 2013 Kernel Summit. When in doubt, the current word of the
0095 devicetree maintainers overrules this document. In that situation, a patch
0096 updating this document would be appreciated.
