diff options
Diffstat (limited to 'Documentation/devicetree/bindings/submitting-patches.rst')
| -rw-r--r-- | Documentation/devicetree/bindings/submitting-patches.rst | 47 |
1 files changed, 34 insertions, 13 deletions
diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst index 8087780f1685..ce767b1eccf2 100644 --- a/Documentation/devicetree/bindings/submitting-patches.rst +++ b/Documentation/devicetree/bindings/submitting-patches.rst @@ -15,9 +15,22 @@ I. For patch submitters "dt-bindings: <binding dir>: ..." + Few subsystems, like ASoC, media, regulators and SPI, expect reverse order + of the prefixes:: + + "<binding dir>: dt-bindings: ..." + The 80 characters of the subject are precious. It is recommended to not - use "Documentation" or "doc" because that is implied. All bindings are - docs. Repeating "binding" again should also be avoided. + 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 @@ -42,27 +55,31 @@ I. For patch submitters 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 text file + 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) 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, ... + 7) DTS is treated in general as driver-independent hardware description, thus + any DTS patches, regardless whether using existing or new bindings, should + be placed at the end of 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. - As in the above example, the known values of "<chip>" should be - documented if it is used. + If a driver subsystem maintainer prefers to apply entire set, instead of + their relevant portion of patchset, please split the DTS patches into + separate patchset with a reference in changelog or cover letter to the + bindings submission on the mailing list. 8) 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). + string that is matched by the driver. + 9) Bindings are actively used by multiple projects other than the Linux + Kernel, extra care and consideration may need to be taken when making changes + to existing bindings. II. For kernel maintainers ========================== @@ -78,9 +95,13 @@ II. For kernel maintainers For subsystem bindings (anything affecting more than a single device), getting a devicetree maintainer to review it is required. - 3) For a series going though multiple trees, the binding patch should be + 3) For a series going through multiple trees, the binding patch should be kept with the driver using the binding. + 4) The DTS files should however never be applied via driver subsystem tree, + but always via platform SoC trees on dedicated branches (see also + Documentation/process/maintainer-soc.rst). + III. Notes ========== |