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