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