92 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3==========================================4Submitting Devicetree (DT) binding patches5==========================================6 7I. For patch submitters8=======================9 10 0) Normal patch submission rules from11 Documentation/process/submitting-patches.rst applies.12 13 1) The Documentation/ and include/dt-bindings/ portion of the patch should14 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 order19 of the prefixes::20 21 "<binding dir>: dt-bindings: ..."22 23 The 80 characters of the subject are precious. It is recommended to not24 use "Documentation" or "doc" because that is implied. All bindings are25 docs. Repeating "binding" again should also be avoided.26 27 2) DT binding files are written in DT schema format using json-schema28 vocabulary and YAML file format. The DT binding files must pass validation29 by running::30 31 make dt_binding_check32 33 See Documentation/devicetree/bindings/writing-schema.rst for more details34 about schema and tools setup.35 36 3) DT binding files should be dual licensed. The preferred license tag is37 (GPL-2.0-only OR BSD-2-Clause).38 39 4) Submit the entire series to the devicetree mailinglist at40 41 devicetree@vger.kernel.org42 43 and Cc: the DT maintainers. Use scripts/get_maintainer.pl to identify44 all of the DT maintainers.45 46 5) The Documentation/ portion of the patch should come in the series before47 the code implementing the binding.48 49 6) Any compatible strings used in a chip or board DTS file must be50 previously documented in the corresponding DT binding file51 in Documentation/devicetree/bindings. This rule applies even if52 the Linux device driver does not yet match on the compatible53 string. [ checkpatch will emit warnings if this step is not54 followed as of commit bff5da4335256513497cc8c79f9a9d1665e0986455 ("checkpatch: add DT compatible string documentation checks"). ]56 57 7) If a documented compatible string is not yet matched by the58 driver, the documentation should also include a compatible59 string that is matched by the driver.60 61 8) Bindings are actively used by multiple projects other than the Linux62 Kernel, extra care and consideration may need to be taken when making changes63 to existing bindings.64 65II. For kernel maintainers66==========================67 68 1) If you aren't comfortable reviewing a given binding, reply to it and ask69 the devicetree maintainers for guidance. This will help them prioritize70 which ones to review and which ones are ok to let go.71 72 2) For driver (not subsystem) bindings: If you are comfortable with the73 binding, and it hasn't received an Acked-by from the devicetree74 maintainers after a few weeks, go ahead and take it.75 76 For subsystem bindings (anything affecting more than a single device),77 getting a devicetree maintainer to review it is required.78 79 3) For a series going though multiple trees, the binding patch should be80 kept with the driver using the binding.81 82III. Notes83==========84 85 0) Please see Documentation/devicetree/bindings/ABI.rst for details86 regarding devicetree ABI.87 88 1) This document is intended as a general familiarization with the process as89 decided at the 2013 Kernel Summit. When in doubt, the current word of the90 devicetree maintainers overrules this document. In that situation, a patch91 updating this document would be appreciated.92