요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
============================================================
DOs and DON'Ts for designing and writing Devicetree bindings
============================================================
This is a list of common review feedback items focused on binding design. With
every rule, there are exceptions and bindings have many gray areas.
For guidelines related to patches, see
Documentation/devicetree/bindings/submitting-patches.rst
Overall design
==============
- DO attempt to make bindings complete even if a driver doesn't support some
features. For example, if a device has an interrupt, then include the
'interrupts' property even if the driver is only polled mode.
- DON'T refer to Linux or "device driver" in bindings. Bindings should be
based on what the hardware has, not what an OS and driver currently support.
- DO use node names matching the class of the device. Many standard names are
defined in the DT Spec. If there isn't one, consider adding it.
- DO check that the example matches the documentation especially after making
review changes.
- DON'T create nodes just for the sake of instantiating drivers. Multi-function
devices only need child nodes when the child nodes have their own DT
resources. A single node can be multiple providers (e.g. clocks and resets).
- DON'T treat device node names as a stable ABI, but instead use phandles or
compatibles to find sibling devices. Exception: sub-nodes of given device
could be treated as ABI, if explicitly documented in the bindings.
- DON'T use 'syscon' alone without a specific compatible string. A 'syscon'
hardware block should have a compatible string unique enough to infer the
register layout of the entire block (at a minimum).
- DON'T use 'simple-mfd' compatible for non-trivial devices, where children
depend on some resources from the parent. Similarly, 'simple-bus' should not
be used for complex buses and even 'regs' property means device is not
a simple bus.
Properties
==========
- DO make 'compatible' properties specific.
- DON'T use wildcards or device-family names in compatible strings.
- DO use fallback compatibles when devices are the same as or a superset of
prior implementations.
- DO add new compatibles in case there are new features or bugs.
- DO use a SoC-specific compatible for all SoC devices, followed by a
fallback if appropriate. SoC-specific compatibles are also preferred for
the fallbacks.
- DON'T use bus suffixes to encode the type of interface device is using.
The parent bus node already implies that interface. DON'T add the type of
device, if the device cannot be anything else.
- DO use a vendor prefix on device-specific property names. Consider if
properties could be common among devices of the same class. Check other
existing bindings for similar devices.
- DON'T redefine common properties. Just reference the definition and define
constraints specific to the device.
- DON'T add properties to avoid a specific compatible. DON'T add properties if
they are implied by (deducible from) the compatible.
- DO use common property unit suffixes for properties with scientific units.
Recommended suffixes are listed at
https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml
- DO define properties in terms of constraints. How many entries? What are
possible values? What is the order? All these constraints represent the ABI
as well.
- DON'T make changes that break the ABI without explicit and detailed rationale
for why the changes have to be made and their impact. ABI impact goes beyond
the Linux kernel, because it also covers other open-source upstream projects.
Typical cases and caveats
=========================
- Phandle entries, like clocks/dmas/interrupts/resets, should always be
explicitly ordered. Include the {clock,dma,interrupt,reset}-names if there is
more than one phandle. When used, both of these fields need the same
constraints (e.g. list of items).
- For names used in {clock,dma,interrupt,reset}-names, do not add any suffix,
e.g.: "tx" instead of "txirq" (for interrupt).
- Properties without schema types (e.g. without standard suffix or not defined
by schema) need the type, even if this is an enum.
- If schema includes other schema (e.g. /schemas/i2c/i2c-controller.yaml) use
"unevaluatedProperties:false". In other cases, usually use
"additionalProperties:false".
- For sub-blocks/components of bigger device (e.g. SoC blocks) use rather
device-based compatible (e.g. SoC-based compatible), instead of custom
versioning of that component.
For example use "vendor,soc1234-i2c" instead of "vendor,i2c-v2".
- "syscon" is not a generic property. Use vendor and type, e.g.
"vendor,power-manager-syscon".
- Do not add instance index (IDs) properties or custom OF aliases. If the
devices have different programming model, they might need different
compatibles. If such devices use some other device in a different way, e.g.
they program the phy differently, use cell/phandle arguments.
- Bindings files should be named like compatible: vendor,device.yaml. In case
of multiple compatibles in the binding, use one of the fallbacks or a more
generic name, yet still matching compatible style.
Board/SoC .dts Files
====================
- DO put all MMIO devices under a bus node and not at the top-level.
- DO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit
platforms don't need all devices to have 64-bit address and size.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Devicetree binding 설계 지침의 범위
1-13이 문서는 Devicetree binding을 설계하고 작성할 때 지켜야 할 사항과 피해야 할 사항을 정리합니다. binding 설계에 초점을 둔 일반적인 review feedback 목록이며, 모든 규칙에는 예외가 있을 수 있고 binding에는 판단이 필요한 회색 영역이 많습니다.
patch 자체에 관한 지침은 `Documentation/devicetree/bindings/submitting-patches.rst`를 참고합니다.
전체 설계 원칙
14-47DO: driver가 일부 기능을 지원하지 않더라도 binding은 가능한 한 완전하게 작성합니다. 예를 들어 장치에 interrupt가 있다면 driver가 polling mode만 지원하더라도 `interrupts` 속성을 포함합니다.
DON'T: binding에서 Linux나 "device driver"를 언급하지 않습니다. binding은 OS와 driver가 현재 지원하는 기능이 아니라 hardware가 가진 기능을 기준으로 해야 합니다.
DO: 장치 class와 일치하는 node 이름을 사용합니다. DT Spec에는 많은 표준 이름이 정의되어 있으며, 적합한 이름이 없다면 표준에 추가하는 것을 고려합니다.
DO: 특히 review 변경을 반영한 뒤에는 예제가 문서와 일치하는지 확인합니다.
DON'T: driver를 인스턴스화하기 위한 목적으로만 node를 만들지 않습니다. multi-function 장치의 child node가 자체 DT resource를 가질 때만 child node가 필요합니다. 하나의 node가 clock과 reset 같은 여러 provider 역할을 동시에 맡을 수 있습니다.
DON'T: device node 이름을 안정적인 ABI로 간주하지 않습니다. sibling 장치를 찾을 때는 phandle이나 `compatible`을 사용합니다. 다만 특정 장치의 sub-node가 binding에 명시적으로 문서화되어 있다면 ABI로 취급할 수 있습니다.
DON'T: 구체적인 compatible 문자열 없이 `syscon`만 사용하지 않습니다. `syscon` hardware block에는 적어도 전체 block의 register layout을 추론할 수 있을 만큼 고유한 compatible 문자열이 있어야 합니다.
DON'T: child가 parent의 일부 resource에 의존하는 non-trivial 장치에 `simple-mfd` compatible을 사용하지 않습니다. 마찬가지로 복잡한 bus에는 `simple-bus`를 사용하지 않으며, `regs` 속성이 있다는 것 자체가 simple bus가 아님을 뜻합니다.
속성 설계 원칙
48-90DO: `compatible` 속성은 구체적으로 만듭니다. compatible 문자열에는 wildcard나 device-family 이름을 사용하지 않습니다.
DO: 장치가 이전 구현과 같거나 이전 구현의 superset이면 fallback compatible을 사용합니다. 새로운 기능이나 bug가 있으면 새 compatible을 추가합니다.
DO: 모든 SoC 장치에는 SoC-specific compatible을 사용하고 적절한 경우 그 뒤에 fallback을 둡니다. fallback에도 SoC-specific compatible을 선호합니다.
DON'T: 장치가 사용하는 interface 유형을 표현하려고 compatible에 bus suffix를 넣지 않습니다. parent bus node가 이미 interface를 나타냅니다. 장치가 다른 유형일 수 없다면 장치 유형도 문자열에 덧붙이지 않습니다.
DO: 장치 전용 속성 이름에는 vendor prefix를 사용합니다. 같은 class의 여러 장치에서 공통으로 쓸 수 있는 속성인지 검토하고, 유사 장치의 기존 binding을 확인합니다.
DON'T: 공통 속성을 다시 정의하지 않습니다. 공통 정의를 참조하고 해당 장치에만 필요한 constraint를 정의합니다.
DON'T: 특정 compatible을 피하려고 속성을 추가하지 않습니다. `compatible`에서 암시되거나 추론할 수 있는 내용이라면 별도 속성을 추가하지 않습니다.
DO: 과학 단위를 쓰는 속성에는 공통 property unit suffix를 사용합니다. 권장 suffix는 `https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml`에 나열되어 있습니다.
DO: 속성을 constraint 관점에서 정의합니다. 항목 수, 가능한 값, 순서를 모두 명시해야 하며 이 constraint들도 ABI의 일부입니다.
DON'T: 변경이 반드시 필요한 이유와 영향에 대한 명시적이고 상세한 근거 없이 ABI를 깨는 변경을 하지 않습니다. ABI 영향 범위는 Linux kernel을 넘어 다른 open-source upstream project까지 포함합니다.
일반적인 사례와 주의점
91-125clock, DMA, interrupt, reset 같은 phandle 항목은 항상 순서를 명시합니다. phandle이 둘 이상이면 `{clock,dma,interrupt,reset}-names`를 포함합니다. 이 두 필드를 함께 사용할 때는 items 목록 같은 동일한 constraint를 적용해야 합니다.
`{clock,dma,interrupt,reset}-names`에 쓰는 이름에는 suffix를 덧붙이지 않습니다. 예를 들어 interrupt 이름은 `txirq` 대신 `tx`를 사용합니다.
표준 suffix가 없거나 schema에서 정의하지 않는 등 schema type이 없는 속성은 enum이더라도 type을 명시해야 합니다.
schema가 `/schemas/i2c/i2c-controller.yaml` 같은 다른 schema를 포함하면 `unevaluatedProperties: false`를 사용합니다. 그 밖의 경우에는 보통 `additionalProperties: false`를 사용합니다.
SoC block처럼 더 큰 장치의 sub-block이나 component에는 component 자체의 사용자 정의 versioning보다 장치 기반 compatible을 사용합니다. 예를 들어 `vendor,i2c-v2` 대신 `vendor,soc1234-i2c`를 사용합니다.
`syscon`은 일반 속성이 아닙니다. `vendor,power-manager-syscon`처럼 vendor와 유형을 나타내는 이름을 사용합니다.
instance index(ID) 속성이나 사용자 정의 OF alias를 추가하지 않습니다. 장치의 programming model이 다르면 서로 다른 compatible이 필요할 수 있습니다. 장치가 PHY를 다르게 program하는 것처럼 다른 장치를 서로 다른 방식으로 사용한다면 cell 또는 phandle argument를 사용합니다.
binding 파일 이름은 compatible과 같은 `vendor,device.yaml` 형식으로 정합니다. 하나의 binding에 compatible이 여러 개라면 fallback 중 하나나 더 일반적인 이름을 사용하되 compatible 형식과 계속 일치해야 합니다.
Board와 SoC DTS 파일
126-132DO: 모든 MMIO 장치는 top-level이 아니라 bus node 아래에 둡니다.
DO: 비어 있지 않은 `ranges`를 사용해 child bus와 장치의 크기를 제한합니다. 64비트 platform이라고 해서 모든 장치가 64비트 address와 size를 가질 필요는 없습니다.
요약과 해설
writing-bindings.rst:1-132Devicetree binding의 hardware 중심 설계, compatible·속성·ABI 규칙과 DTS 배치 원칙을 설명합니다. 접을 수 있는 영어 원문 전체와 한국어 전문 번역을 함께 제공하며, compatible, property, phandle, ABI, source path, URL과 줄 좌표는 원문 표기를 보존합니다.