mirror of
https://github.com/torvalds/linux.git
synced 2026-04-18 06:44:00 -04:00
ee2fe81cdc
Pull documentation updates from Jonathan Corbet:
"It has been a relatively busy cycle in docsland, with changes all
over:
- Bring the kernel memory-model docs into the Sphinx build in the
"literal include" mode.
- Lots of build-infrastructure work, further cleaning up long-term
kernel-doc technical debt. The sphinx-pre-install tool has been
converted to Python and updated for current systems.
- A new tool to detect when documents have been moved and generate
HTML redirects; this can be used on kernel.org (or any other site
hosting the rendered docs) to avoid breaking links.
- Automated processing of the YAML files describing the netlink
protocol.
- A significant update of the maintainer's PGP guide.
... and a seemingly endless series of typo fixes, build-problem fixes,
etc"
* tag 'docs-6.18' of git://git.lwn.net/linux: (193 commits)
Documentation/features: Update feature lists for 6.17-rc7
docs: remove cdomain.py
Documentation/process: submitting-patches: fix typo in "were do"
docs: dev-tools/lkmm: Fix typo of missing file extension
Documentation: trace: histogram: Convert ftrace docs cross-reference
Documentation: trace: histogram-design: Wrap introductory note in note:: directive
Documentation: trace: historgram-design: Separate sched_waking histogram section heading and the following diagram
Documentation: trace: histogram-design: Trim trailing vertices in diagram explanation text
Documentation: trace: histogram: Fix histogram trigger subsection number order
docs: driver-api: fix spelling of "buses".
Documentation: fbcon: Use admonition directives
Documentation: fbcon: Reindent 8th step of attach/detach/unload
Documentation: fbcon: Add boot options and attach/detach/unload section headings
docs: filesystems: sysfs: add remaining top level sysfs directory descriptions
docs: filesystems: sysfs: clarify symlink destinations in dev and bus/devices descriptions
docs: filesystems: sysfs: remove top level sysfs net directory
docs: maintainer: Fix ambiguous subheading formatting
docs: kdoc: a few more dump_typedef() tweaks
docs: kdoc: remove redundant comment stripping in dump_typedef()
docs: kdoc: remove some dead code in dump_typedef()
...
115 lines
4.7 KiB
ReStructuredText
115 lines
4.7 KiB
ReStructuredText
.. 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 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", "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 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.
|
|
|
|
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.
|
|
|
|
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
|
|
==========================
|
|
|
|
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.
|
|
|
|
For subsystem bindings (anything affecting more than a single device),
|
|
getting a devicetree maintainer to review it is required.
|
|
|
|
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
|
|
==========
|
|
|
|
0) Please see Documentation/devicetree/bindings/ABI.rst 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.
|