Commit | Line | Data |
---|---|---|
858e6845 | 1 | .. SPDX-License-Identifier: GPL-2.0 |
2a933001 | 2 | |
858e6845 | 3 | ========================================== |
7248213c | 4 | Submitting Devicetree (DT) binding patches |
858e6845 | 5 | ========================================== |
2a933001 JC |
6 | |
7 | I. For patch submitters | |
858e6845 | 8 | ======================= |
2a933001 | 9 | |
6dce82b2 MCC |
10 | 0) Normal patch submission rules from |
11 | Documentation/process/submitting-patches.rst applies. | |
2a933001 | 12 | |
44acf105 | 13 | 1) The Documentation/ and include/dt-bindings/ portion of the patch should |
858e6845 | 14 | be a separate patch. The preferred subject prefix for binding patches is:: |
44acf105 RH |
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. | |
2a933001 | 21 | |
70145d16 RH |
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 | |
858e6845 | 24 | by running:: |
70145d16 RH |
25 | |
26 | make dt_binding_check | |
27 | ||
6dce82b2 MCC |
28 | See Documentation/devicetree/bindings/writing-schema.rst for more details |
29 | about schema and tools setup. | |
70145d16 RH |
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 | |
2a933001 JC |
35 | |
36 | devicetree@vger.kernel.org | |
37 | ||
d1e9fa98 MP |
38 | and Cc: the DT maintainers. Use scripts/get_maintainer.pl to identify |
39 | all of the DT maintainers. | |
40 | ||
70145d16 | 41 | 5) The Documentation/ portion of the patch should come in the series before |
ef0b97e3 JMC |
42 | the code implementing the binding. |
43 | ||
70145d16 | 44 | 6) Any compatible strings used in a chip or board DTS file must be |
10638a4e PW |
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 | ||
70145d16 | 52 | 7) The wildcard "<chip>" may be used in compatible strings, as in |
10638a4e PW |
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 | ||
70145d16 | 61 | 8) If a documented compatible string is not yet matched by the |
10638a4e PW |
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 | ||
c9dcc63e TR |
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. | |
10638a4e | 69 | |
2a933001 | 70 | II. For kernel maintainers |
858e6845 | 71 | ========================== |
2a933001 JC |
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 | ||
e3c2b1ed GU |
81 | For subsystem bindings (anything affecting more than a single device), |
82 | getting a devicetree maintainer to review it is required. | |
2a933001 JC |
83 | |
84 | 3) For a series going though multiple trees, the binding patch should be | |
85 | kept with the driver using the binding. | |
86 | ||
87 | III. Notes | |
858e6845 | 88 | ========== |
2a933001 | 89 | |
6dce82b2 MCC |
90 | 0) Please see Documentation/devicetree/bindings/ABI.rst for details |
91 | regarding devicetree ABI. | |
2a933001 JC |
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. |