요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
===================
Devicetree (DT) ABI
===================
I. Regarding stable bindings/ABI, we quote from the 2013 ARM mini-summit
summary document:
"That still leaves the question of, what does a stable binding look
like? Certainly a stable binding means that a newer kernel will not
break on an older device tree, but that doesn't mean the binding is
frozen for all time. Grant said there are ways to change bindings that
don't result in breakage. For instance, if a new property is added,
then default to the previous behaviour if it is missing. If a binding
truly needs an incompatible change, then change the compatible string
at the same time. The driver can bind against both the old and the
new. These guidelines aren't new, but they desperately need to be
documented."
II. General binding rules
1) Maintainers, don't let perfect be the enemy of good. Don't hold up a
binding because it isn't perfect.
2) Use specific compatible strings so that if we need to add a feature (DMA)
in the future, we can create a new compatible string. See I.
3) Bindings can be augmented, but the driver shouldn't break when given
the old binding. ie. add additional properties, but don't change the
meaning of an existing property. For drivers, default to the original
behaviour when a newly added property is missing.
4) Don't submit bindings for staging or unstable. That will be decided by
the devicetree maintainers *after* discussion on the mailinglist.
III. Notes
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의 의미
1-19SPDX 라이선스 식별자: GPL-2.0
Devicetree, 즉 DT ABI
안정적인 binding과 ABI에 관해서는 2013 ARM mini-summit 요약 문서를 인용합니다.
안정적인 binding이란 새 kernel이 오래된 device tree에서 동작하지 않게 되는 일이 없다는 뜻이지만, binding이 영원히 고정된다는 뜻은 아닙니다. Grant는 호환성을 깨뜨리지 않고 binding을 변경할 방법이 있다고 설명했습니다.
예를 들어 새 property를 추가한다면 그 property가 없을 때 이전 behavior를 기본값으로 사용해야 합니다. 정말로 호환되지 않는 변경이 필요하다면 `compatible` string도 동시에 바꿔야 하며, driver는 기존 string과 새 string 양쪽에 bind할 수 있습니다. 이런 지침은 새롭지 않지만 반드시 문서화해야 합니다.
기존 device tree를 보존하면서 새 기능을 도입하는 두 경로입니다.
일반 binding 규칙
20-36일반 binding 규칙
1. Maintainer는 완벽함이 좋은 결과를 막게 해서는 안 됩니다. Binding이 완벽하지 않다는 이유만으로 진행을 지연시키지 마십시오.
2. 구체적인 `compatible` string을 사용해야 합니다. 그러면 미래에 DMA 같은 기능을 추가할 때 새 `compatible` string을 만들 수 있습니다.
3. Binding은 확장할 수 있지만 오래된 binding이 주어졌을 때 driver가 깨져서는 안 됩니다. Property는 추가할 수 있지만 기존 property의 의미는 바꾸지 마십시오. 새로 추가된 property가 없으면 driver는 원래 behavior를 기본값으로 사용해야 합니다.
4. Staging 또는 unstable 상태를 위한 binding은 제출하지 마십시오. 해당 여부는 mailinglist 논의 후 Devicetree maintainer가 결정합니다.
문서 적용 범위와 최신 maintainer 판단
37-42참고
이 문서는 2013 Kernel Summit에서 결정한 절차를 전반적으로 익히기 위한 것입니다. 판단이 불확실할 때는 현재 Devicetree maintainer의 지침이 이 문서보다 우선합니다. 그런 상황에서는 이 문서를 갱신하는 patch도 함께 제출하는 것이 바람직합니다.
요약과 해설
ABI.rst:1-42안정적인 DT ABI는 binding을 영구 동결하는 것이 아니라 오래된 device tree가 새 kernel에서도 계속 동작하도록 property와 compatible string을 진화시키는 원칙입니다.