요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. 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
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.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Devicetree binding patch 제출
1-9이 GPL-2.0 문서는 Devicetree(DT) binding patch를 제출하는 사람과 kernel maintainer가 따라야 할 절차를 정리합니다. 첫 부분은 patch submitter를 위한 규칙입니다.
Patch 분리와 제목 형식
10-340) 일반 patch 제출 규칙은 `Documentation/process/submitting-patches.rst`를 따릅니다.
1) Patch의 `Documentation/` 및 `include/dt-bindings/` 부분은 별도 patch로 만들어야 합니다. Binding patch의 권장 subject prefix는 다음 형식입니다.
"dt-bindings: <binding dir>: ..."ASoC, media, regulator, SPI 같은 일부 subsystem은 prefix의 역순을 기대합니다.
"<binding dir>: dt-bindings: ..."Subject의 80자는 귀중하므로 이미 의미가 포함된 `Documentation`, `doc`, `YAML`은 쓰지 않는 편이 좋습니다. 모든 binding은 문서이고 새 binding은 Devicetree schema 형식이어야 하므로 `binding`을 반복하는 것도 피합니다. 새 device에는 다음 정도면 충분합니다.
"dt-bindings: iio: adc: Add ROHM BD79100G"다른 형식의 문서를 DT schema로 변환할 때는 다음 제목 형식을 사용합니다.
"dt-bindings: iio: adc: adi,ad7476: Convert to DT schema"Schema 검사·license·메일 제출 순서
35-552) DT binding 파일은 json-schema vocabulary와 YAML file format을 사용하는 DT schema 형식으로 작성합니다. 다음 명령으로 validation을 통과해야 합니다.
make dt_binding_checkSchema와 tool 설정의 자세한 내용은 `Documentation/devicetree/bindings/writing-schema.rst`를 참고합니다.
3) DT binding 파일은 dual license를 권장하며 선호하는 license tag는 `(GPL-2.0-only OR BSD-2-Clause)`입니다.
4) 전체 series를 `[email protected]` mailing list로 보내고 DT maintainer들을 Cc에 넣습니다. 모든 DT maintainer를 찾으려면 `scripts/get_maintainer.pl`을 사용합니다.
5) Series에서는 patch의 `Documentation/` 부분이 해당 binding을 구현하는 code보다 앞에 와야 합니다.
Compatible 문서화와 DTS 배치
56-836) Chip 또는 board DTS 파일에서 사용하는 모든 compatible string은 먼저 `Documentation/devicetree/bindings`의 대응 DT binding 파일에 문서화되어야 합니다. Linux device driver가 아직 그 compatible에 match하지 않아도 이 규칙을 적용합니다. 이를 지키지 않으면 commit `bff5da4335256513497cc8c79f9a9d1665e09864`의 compatible string 문서 검사에 따라 checkpatch가 warning을 냅니다.
7) DTS는 일반적으로 driver와 독립적인 hardware description으로 취급합니다. 기존 binding을 쓰든 새 binding을 쓰든 DTS patch는 driver가 DTS에 의존하지 않음을 나타내도록 patchset 끝에 둡니다. DTS는 별도 tree 또는 branch를 통해 적용되므로 다른 순서는 series가 bisect 가능하지 않다는 인상을 줍니다.
Driver subsystem maintainer가 patchset 중 자기 부분만이 아니라 전체 set 적용을 원한다면 DTS patch를 별도 patchset으로 분리하고, changelog나 cover letter에서 mailing list의 binding 제출을 참조합니다.
8) 문서화한 compatible string을 driver가 아직 match하지 않는다면, 문서에는 driver가 match하는 compatible string도 함께 포함해야 합니다.
9) Binding은 Linux Kernel 외의 여러 project에서도 활발히 사용하므로 기존 binding을 변경할 때는 추가적인 주의와 검토가 필요할 수 있습니다.
Kernel maintainer의 review 판단
84-971) 특정 binding을 review하기 어렵다면 해당 patch에 답장해 devicetree maintainer에게 지침을 요청합니다. 그러면 그들이 우선 review할 항목과 그대로 진행해도 되는 항목을 판단하는 데 도움이 됩니다.
2) Subsystem 전체가 아닌 driver binding은 담당 maintainer가 내용을 자신 있게 판단할 수 있고 몇 주가 지나도 devicetree maintainer의 `Acked-by`가 없다면 직접 가져가도 됩니다. 반면 단일 device보다 넓게 영향을 주는 subsystem binding은 devicetree maintainer의 review가 필수입니다.
여러 tree와 DTS 적용 경로
98-1043) 여러 tree를 거치는 series에서는 binding patch를 그 binding을 사용하는 driver와 함께 유지합니다.
4) DTS 파일은 driver subsystem tree로 적용하지 말고 항상 전용 branch의 platform SoC tree를 통해 적용해야 합니다. `Documentation/process/maintainer-soc.rst`도 참고합니다.
ABI와 현재 maintainer 판단
105-1140) Devicetree ABI의 자세한 내용은 `Documentation/devicetree/bindings/ABI.rst`를 참고합니다.
1) 이 문서는 2013 Kernel Summit에서 결정한 절차를 일반적으로 익히기 위한 것입니다. 의문이 생기면 현재 devicetree maintainer의 판단이 이 문서보다 우선하며, 그런 경우 이 문서를 갱신하는 patch도 환영합니다.
요약과 해설
submitting-patches.rst:1-114DT binding patch의 분리, 제목, schema 검사, mailing list 제출과 maintainer review 절차를 설명합니다. 접을 수 있는 영어 원문 전체와 줄 좌표를 보존하고, 한국어 전문 번역에서는 command·prefix·compatible·commit ID·mail address·source path를 원형대로 유지합니다.