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