submitting-patches.rst 3.5 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091
  1. .. SPDX-License-Identifier: GPL-2.0
  2. ==========================================
  3. Submitting devicetree (DT) binding patches
  4. ==========================================
  5. I. For patch submitters
  6. =======================
  7. 0) Normal patch submission rules from Documentation/process/submitting-patches.rst
  8. applies.
  9. 1) The Documentation/ and include/dt-bindings/ portion of the patch should
  10. be a separate patch. The preferred subject prefix for binding patches is::
  11. "dt-bindings: <binding dir>: ..."
  12. The 80 characters of the subject are precious. It is recommended to not
  13. use "Documentation" or "doc" because that is implied. All bindings are
  14. docs. Repeating "binding" again should also be avoided.
  15. 2) DT binding files are written in DT schema format using json-schema
  16. vocabulary and YAML file format. The DT binding files must pass validation
  17. by running::
  18. make dt_binding_check
  19. See ../writing-schema.rst for more details about schema and tools setup.
  20. 3) DT binding files should be dual licensed. The preferred license tag is
  21. (GPL-2.0-only OR BSD-2-Clause).
  22. 4) Submit the entire series to the devicetree mailinglist at
  23. devicetree@vger.kernel.org
  24. and Cc: the DT maintainers. Use scripts/get_maintainer.pl to identify
  25. all of the DT maintainers.
  26. 5) The Documentation/ portion of the patch should come in the series before
  27. the code implementing the binding.
  28. 6) Any compatible strings used in a chip or board DTS file must be
  29. previously documented in the corresponding DT binding text file
  30. in Documentation/devicetree/bindings. This rule applies even if
  31. the Linux device driver does not yet match on the compatible
  32. string. [ checkpatch will emit warnings if this step is not
  33. followed as of commit bff5da4335256513497cc8c79f9a9d1665e09864
  34. ("checkpatch: add DT compatible string documentation checks"). ]
  35. 7) The wildcard "<chip>" may be used in compatible strings, as in
  36. the following example:
  37. - compatible: Must contain '"nvidia,<chip>-pcie",
  38. "nvidia,tegra20-pcie"' where <chip> is tegra30, tegra132, ...
  39. As in the above example, the known values of "<chip>" should be
  40. documented if it is used.
  41. 8) If a documented compatible string is not yet matched by the
  42. driver, the documentation should also include a compatible
  43. string that is matched by the driver (as in the "nvidia,tegra20-pcie"
  44. example above).
  45. II. For kernel maintainers
  46. ==========================
  47. 1) If you aren't comfortable reviewing a given binding, reply to it and ask
  48. the devicetree maintainers for guidance. This will help them prioritize
  49. which ones to review and which ones are ok to let go.
  50. 2) For driver (not subsystem) bindings: If you are comfortable with the
  51. binding, and it hasn't received an Acked-by from the devicetree
  52. maintainers after a few weeks, go ahead and take it.
  53. Subsystem bindings (anything affecting more than a single device)
  54. then getting a devicetree maintainer to review it is required.
  55. 3) For a series going though multiple trees, the binding patch should be
  56. kept with the driver using the binding.
  57. III. Notes
  58. ==========
  59. 0) Please see ...bindings/ABI.txt for details regarding devicetree ABI.
  60. 1) This document is intended as a general familiarization with the process as
  61. decided at the 2013 Kernel Summit. When in doubt, the current word of the
  62. devicetree maintainers overrules this document. In that situation, a patch
  63. updating this document would be appreciated.