Devicetree Bindings Build and Validation Makefile

검증 도구와 최소 버전

이 Makefile은 devicetree binding 문서 검증에 쓰는 명령을 정의합니다. `DT_DOC_CHECKER`의 기본값은 `dt-doc-validate`, `DT_EXTRACT_EX`는 `dt-extract-example`, `DT_MK_SCHEMA`는 `dt-mk-schema`입니다. `yamllint`가 있으면 `DT_SCHEMA_LINT`에 그 경로를 저장하고, 없으면 경고를 출력한 뒤 lint를 건너뜁니다. 요구하는 dtschema 최소 버전은 `2023.9`입니다.

# SPDX-License-Identifier: GPL-2.0
DT_DOC_CHECKER ?= dt-doc-validate
DT_EXTRACT_EX ?= dt-extract-example
DT_MK_SCHEMA ?= dt-mk-schema

DT_SCHEMA_LINT = $(shell which yamllint || \
  echo "warning: python package 'yamllint' not installed, skipping" >&2)

DT_SCHEMA_MIN_VERSION = 2023.9

dtschema 설치와 버전 검사

`check_dtschema_version` phony target은 `DT_DOC_CHECKER`가 `PATH`에 있는지 확인합니다. 없으면 설치 안내와 현재 `PATH`를 stderr에 출력하고 실패합니다. 이어 최소 버전과 실제 `--version` 결과를 version sort로 비교하며, 실제 버전이 `2023.9`보다 낮으면 오류로 종료합니다.

PHONY += check_dtschema_version
check_dtschema_version:
        @which $(DT_DOC_CHECKER) >/dev/null || \
                { echo "Error: '$(DT_DOC_CHECKER)' not found!" >&2; \
                  echo "Ensure dtschema python package is installed and in your PATH." >&2; \
                  echo "Current PATH is:" >&2; \
                  echo "$$PATH" >&2; false; }
        @{ echo $(DT_SCHEMA_MIN_VERSION); \
        $(DT_DOC_CHECKER) --version 2>/dev/null || echo 0; } | sort -Vc >/dev/null || \
        { echo "ERROR: dtschema minimum version is v$(DT_SCHEMA_MIN_VERSION)" >&2; false; }

예제 추출과 YAML 경로 선택

`extract_ex` 명령은 선택한 YAML의 embedded example을 DTS로 추출합니다. `find_all_cmd`는 source tree의 모든 `*.yaml`을 찾되 `processed-schema*`는 제외합니다. `find_cmd`는 `DT_SCHEMA_FILES`에 지정된 colon-separated filter와 일치하는 경로만 골라 다시 source tree 절대 경로로 만듭니다.

`CHK_DT_EXAMPLES`는 이 YAML 목록을 대응하는 `%.example.dtb` target 목록으로 바꿉니다. 각 `%.example.dts`는 YAML, version check, `FORCE`에 의존하고 `if_changed,extract_ex`로 생성됩니다.

quiet_cmd_extract_ex = DTEX    $@
      cmd_extract_ex = $(DT_EXTRACT_EX) $< > $@

$(obj)/%.example.dts: $(src)/%.yaml check_dtschema_version FORCE
        $(call if_changed,extract_ex)

find_all_cmd = find $(src) \( -name '*.yaml' ! \
                -name 'processed-schema*' \)

find_cmd = $(find_all_cmd) | \
                sed 's|^$(srctree)/||' | \
                grep -F -e "$(subst :," -e ",$(DT_SCHEMA_FILES))" | \
                sed 's|^|$(srctree)/|'
CHK_DT_EXAMPLES := $(patsubst $(srctree)/%.yaml,%.example.dtb, $(shell $(find_cmd)))

YAML lint, binding 검사와 schema 생성

`yamllint` 명령은 선택한 파일을 최대 200개씩 `nproc` 병렬 process에 넘기고 `.yamllint` 설정으로 parsable 형식의 결과를 stderr에 출력합니다. 성공하면 stamp file을 touch하며, 명령 전체는 실패해도 build를 계속하도록 `|| true`를 둡니다.

`chk_bindings`도 최대 200개씩 병렬로 `dt-doc-validate -u $(src)`에 전달하고 stamp file을 만듭니다. `mk_schema`는 임시 파일에 모든 YAML 경로를 기록한 뒤 `dt-mk-schema -j`로 `processed-schema.json`을 만들고 임시 파일을 제거합니다.

quiet_cmd_yamllint = LINT    $(src)
      cmd_yamllint = ($(find_cmd) | \
                     xargs -n200 -P$$(nproc) \
                     $(DT_SCHEMA_LINT) -f parsable -c $(src)/.yamllint >&2) \
                     && touch $@ || true

quiet_cmd_chk_bindings = CHKDT   $(src)
      cmd_chk_bindings = ($(find_cmd) | \
                          xargs -n200 -P$$(nproc) $(DT_DOC_CHECKER) -u $(src)) \
                          && touch $@ || true

quiet_cmd_mk_schema = SCHEMA  $@
      cmd_mk_schema = f=$$(mktemp) ; \
                      $(find_all_cmd) > $$f ; \
                      $(DT_MK_SCHEMA) -j $(DT_MK_SCHEMA_FLAGS) @$$f > $@ ; \
                      rm -f $$f

DTC warning과 생성 target

`DT_DOCS`는 source tree prefix를 제거한 전체 binding 문서 목록입니다. 예제 compile에는 `avoid_unnecessary_addr_size`, `graph_child_address`, `unique_unit_address` warning을 끄고, 활성화된 unit address의 고유성은 `unique_unit_address_if_enabled`로 검사합니다.

`processed-schema.json`은 모든 문서와 version check에 의존합니다. `.yamllint.checked`와 `.dt-binding.checked` stamp target을 등록하며, yamllint가 없으면 해당 호출을 생략합니다. 통합 schema는 항상 생성하고, 선택된 example의 DTB와 DTS도 target 목록에 추가합니다.

DT_DOCS = $(patsubst $(srctree)/%,%,$(shell $(find_all_cmd)))

override DTC_FLAGS := \
        -Wno-avoid_unnecessary_addr_size \
        -Wno-graph_child_address \
        -Wno-unique_unit_address \
        -Wunique_unit_address_if_enabled

$(obj)/processed-schema.json: $(DT_DOCS) check_dtschema_version FORCE
        $(call if_changed,mk_schema)

targets += .dt-binding.checked .yamllint.checked
$(obj)/.yamllint.checked: $(DT_DOCS) $(src)/.yamllint FORCE
        $(if $(DT_SCHEMA_LINT),$(call if_changed,yamllint),)

$(obj)/.dt-binding.checked: $(DT_DOCS) FORCE
        $(call if_changed,chk_bindings)

always-y += processed-schema.json
targets += $(patsubst $(obj)/%,%, $(CHK_DT_EXAMPLES))
targets += $(patsubst $(obj)/%.dtb,%.dts, $(CHK_DT_EXAMPLES))

정리와 공개 검사 target

`make clean`에서 argument list가 너무 길어지는 문제를 피하려고 `clean-files` 계산 시 `*.example.dts`와 `*.example.dtb`를 먼저 `find -delete`로 제거합니다. `dt_compatible_check`는 통합 schema를 만든 뒤 kernel tree의 compatible 문자열을 추출해 `dt-check-compatible -v -s`로 검사합니다.

공개 phony target `dt_binding_check`는 binding 검증 stamp, YAML lint stamp, 선택된 모든 example DTB에 의존하므로 이 세 검증 경로를 한 번에 실행합니다.

# Hack: avoid 'Argument list too long' error for 'make clean'. Remove most of
# build artifacts here before they are processed by scripts/Makefile.clean
clean-files = $(shell find $(obj) \( -name '*.example.dts' -o \
                        -name '*.example.dtb' \) -delete 2>/dev/null)

dt_compatible_check: $(obj)/processed-schema.json
        $(Q)$(srctree)/scripts/dtc/dt-extract-compatibles $(srctree) | xargs dt-check-compatible -v -s $<

PHONY += dt_binding_check
dt_binding_check: $(obj)/.dt-binding.checked $(obj)/.yamllint.checked $(CHK_DT_EXAMPLES)