[linux-block.git] / Documentation / devicetree / bindings / submitting-patches.txt


  Submitting devicetree (DT) binding patches

I. For patch submitters

  0) Normal patch submission rules from Documentation/SubmittingPatches
     applies.

  1) The Documentation/ portion of the patch should be a separate patch.

  2) Submit the entire series to the devicetree mailinglist at

       devicetree@vger.kernel.org

  3) The Documentation/ portion of the patch should come in the series before
     the code implementing the binding.

  4) Any compatible strings used in a chip or board DTS file must be
     previously documented in the corresponding DT binding text file
     in Documentation/devicetree/bindings.  This rule applies even if
     the Linux device driver does not yet match on the compatible
     string.  [ checkpatch will emit warnings if this step is not
     followed as of commit bff5da4335256513497cc8c79f9a9d1665e09864
     ("checkpatch: add DT compatible string documentation checks"). ]

  5) The wildcard "<chip>" may be used in compatible strings, as in
     the following example:

         - compatible: Must contain '"nvidia,<chip>-pcie",
           "nvidia,tegra20-pcie"' where <chip> is tegra30, tegra132, ...

     As in the above example, the known values of "<chip>" should be
     documented if it is used.

  6) If a documented compatible string is not yet matched by the
     driver, the documentation should also include a compatible
     string that is matched by the driver (as in the "nvidia,tegra20-pcie"
     example above).


II. For kernel maintainers

  1) If you aren't comfortable reviewing a given binding, reply to it and ask
     the devicetree maintainers for guidance.  This will help them prioritize
     which ones to review and which ones are ok to let go.

  2) For driver (not subsystem) bindings: If you are comfortable with the
     binding, and it hasn't received an Acked-by from the devicetree
     maintainers after a few weeks, go ahead and take it.

     Subsystem bindings (anything affecting more than a single device)
     then getting a devicetree maintainer to review it is required.

  3) For a series going though multiple trees, the binding patch should be
     kept with the driver using the binding.

III. Notes

  0) Please see ...bindings/ABI.txt for details regarding devicetree ABI.

  1) This document is intended as a general familiarization with the process as
     decided at the 2013 Kernel Summit.  When in doubt, the current word of the
     devicetree maintainers overrules this document.  In that situation, a patch
     updating this document would be appreciated.
Commit	Line	Data
2a933001 JC	1
	2	Submitting devicetree (DT) binding patches
	3
	4	I. For patch submitters
	5
	6	0) Normal patch submission rules from Documentation/SubmittingPatches
	7	applies.
	8
	9	1) The Documentation/ portion of the patch should be a separate patch.
	10
	11	2) Submit the entire series to the devicetree mailinglist at
	12
	13	devicetree@vger.kernel.org
	14
ef0b97e3 JMC	15	3) The Documentation/ portion of the patch should come in the series before
	16	the code implementing the binding.
	17
10638a4e PW	18	4) Any compatible strings used in a chip or board DTS file must be
	19	previously documented in the corresponding DT binding text file
	20	in Documentation/devicetree/bindings. This rule applies even if
	21	the Linux device driver does not yet match on the compatible
	22	string. [ checkpatch will emit warnings if this step is not
	23	followed as of commit bff5da4335256513497cc8c79f9a9d1665e09864
	24	("checkpatch: add DT compatible string documentation checks"). ]
	25
	26	5) The wildcard "<chip>" may be used in compatible strings, as in
	27	the following example:
	28
	29	- compatible: Must contain '"nvidia,<chip>-pcie",
	30	"nvidia,tegra20-pcie"' where <chip> is tegra30, tegra132, ...
	31
	32	As in the above example, the known values of "<chip>" should be
	33	documented if it is used.
	34
	35	6) If a documented compatible string is not yet matched by the
	36	driver, the documentation should also include a compatible
	37	string that is matched by the driver (as in the "nvidia,tegra20-pcie"
	38	example above).
	39
	40
2a933001 JC	41	II. For kernel maintainers
	42
	43	1) If you aren't comfortable reviewing a given binding, reply to it and ask
	44	the devicetree maintainers for guidance. This will help them prioritize
	45	which ones to review and which ones are ok to let go.
	46
	47	2) For driver (not subsystem) bindings: If you are comfortable with the
	48	binding, and it hasn't received an Acked-by from the devicetree
	49	maintainers after a few weeks, go ahead and take it.
	50
	51	Subsystem bindings (anything affecting more than a single device)
	52	then getting a devicetree maintainer to review it is required.
	53
	54	3) For a series going though multiple trees, the binding patch should be
	55	kept with the driver using the binding.
	56
	57	III. Notes
	58
	59	0) Please see ...bindings/ABI.txt for details regarding devicetree ABI.
	60
	61	1) This document is intended as a general familiarization with the process as
	62	decided at the 2013 Kernel Summit. When in doubt, the current word of the
	63	devicetree maintainers overrules this document. In that situation, a patch
	64	updating this document would be appreciated.