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