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