Documentation/devicetree/bindings/submitting-patches.rst

Source file repositories/reference/linux-study-clean/Documentation/devicetree/bindings/submitting-patches.rst

File Facts

System
Linux kernel
Corpus path
Documentation/devicetree/bindings/submitting-patches.rst
Extension
.rst
Size
4882 bytes
Lines
116
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

==========================================
Submitting Devicetree (DT) binding patches
==========================================

I. For patch submitters
=======================

  0) Normal patch submission rules from
     Documentation/process/submitting-patches.rst applies.

  1) The Documentation/ and include/dt-bindings/ portion of the patch should
     be a separate patch. The preferred subject prefix for binding patches is::

       "dt-bindings: <binding dir>: ..."

     Few subsystems, like ASoC, media, regulators, SCSI, SPI and UFS, expect
     reverse order of the prefixes, based on subsystem name::

       "<binding dir>: dt-bindings: ..."

     The 80 characters of the subject are precious. It is recommended to not
     use "Documentation", "doc" or "YAML" because that is implied. All
     bindings are docs and all new bindings are supposed to be in Devicetree
     schema format.  Repeating "binding" again should also be avoided, so for
     a new device it is often enough for example::

       "dt-bindings: iio: adc: Add ROHM BD79100G"

     Conversion of other formats to DT schema::

       "dt-bindings: iio: adc: adi,ad7476: Convert to DT schema"

  2) DT binding files are written in DT schema format using json-schema
     vocabulary and YAML file format. The DT binding files must pass validation
     by running::

       make dt_binding_check

     See Documentation/devicetree/bindings/writing-schema.rst for more details
     about schema and tools setup.

  3) DT binding files should be dual licensed. The preferred license tag is
     (GPL-2.0-only OR BSD-2-Clause).

  4) Submit the entire series to the devicetree mailinglist at

       devicetree@vger.kernel.org

     and Cc: the DT maintainers. Use scripts/get_maintainer.pl to identify
     all of the DT maintainers.

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

  6) Any compatible strings used in a chip or board DTS file must be
     previously documented in the corresponding DT binding 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"). ]

  7) DTS is treated in general as driver-independent hardware description, thus
     any DTS patches, regardless whether using existing or new bindings, should
     be a separate posting or, when combined with driver patches, placed at the
     end of the patchset to indicate no dependency of drivers on the DTS.  DTS
     will be anyway applied through separate tree or branch, so different order
     would indicate the series is non-bisectable.

Annotation

Implementation Notes