보드 대상은 파일 하나가 아니라 입력의 조합이다
보드 포팅은 DTS 하나 추가하는 일이 아니다. Zephyr v3.7.0의 hardware model v2에서는 먼저 SoC 지원이 있어야 하고, board.yml이 보드 이름과 허용 SoC를 알린다. nrf52840dk/nrf52840처럼 슬래시 뒤의 qualifier가 구체적인 빌드 대상을 고른다. 선택된 대상에 맞는 DTS와 Kconfig 입력이 합쳐져 firmware image를 만든다. 공식 Board Porting Guide는 이 모델이 v3.6 이후 도입되어 v3.7.0에 적용됐다고 설명한다.
빌드, 보드에 쓰기, 실제 실행은 각각 검증한다. west build 성공은 west flash runner나 실물 보드의 콘솔·타이머·핀 연결까지 보증하지 않는다.
board.cmake는 빌드 대상 인식의 필수 입력이 아니라 flash/debug runner 설정이다. 화살표는 파일 사이의 런타임 상태 전이가 아니라 빌드 도구가 소비하는 입력과 산출물 관계를 뜻한다. 작은 화면에서는 그림을 좌우로 스크롤해 읽을 수 있다.
| 결정 | 입력 | 직접 확인할 결과 |
|---|---|---|
| 보드 대상 선택 | board.yml, 지원 SoC, qualifier | 선택한 -b 대상과 configure 로그 |
| 하드웨어·소프트웨어 구성 | board DTS/overlay, Kconfig.<board>, defconfig, application 설정 | build/zephyr/zephyr.dts, build/zephyr/.config |
| flash/debug | 선택적 board.cmake와 runner 도구 | west flash --context와 장비 관찰 결과 |
v3.7.0에 고정한 원본과 문서
아래 경로와 물리 행은 공식 v3.7.0 태그가 가리키는 commit 36940db938a8f4a1e919496793ed439850a221c2의 파일에서 확인했다. 각 원문은 Git blob과 SHA-256을 대조했다. 보드 포팅 지침과 nRF52840 DK 안내도 같은 릴리스의 문서다.
| 고정 원본 | 이 글에서 확인한 범위 | 역할 |
|---|---|---|
board.yml | 1–8행 | 이름과 두 SoC qualifier |
Kconfig.nrf52840dk | 4–6행 | 대상별 SoC 선택 |
nrf52840dk_nrf52840.dts | 7–18행, 120–133행 | SoC include, chosen, alias |
nrf52840dk_nrf52840_defconfig | 12–20행 | 보드 기본 설정 조각 |
board.cmake | 3–9행 | flash/debug runner |
실제 보드 파일로 보는 다섯 역할
아래 코드는 설명을 위해 만든 모형이 아니라 같은 commit의 짧은 원문 발췌다. 생략된 부분은 링크한 파일에서 확인할 수 있다.
1. board.yml: 이름과 허용 SoC
Zephyr v3.7.0 고정 원문 boards/nordic/nrf52840dk/board.yml 1–8행
board:
name: nrf52840dk
vendor: nordic
socs:
# Physical nRF52840 SoC on PCA10056
- name: nrf52840
# nRF52840 SoC in nRF52811 emulation mode on PCA10056
- name: nrf52811nrf52840dk라는 보드 아래 실제 nRF52840과 nRF52811 에뮬레이션 대상을 선언한다. qualifier는 nrf52840dk/nrf52840처럼 대상 이름에 붙으며, 단일 런타임 상태가 아니다.
2. Kconfig: 대상에 맞는 SoC 선택
Zephyr v3.7.0 고정 원문 boards/nordic/nrf52840dk/Kconfig.nrf52840dk 4–6행
config BOARD_NRF52840DK
select SOC_NRF52840_QIAA if BOARD_NRF52840DK_NRF52840
select SOC_NRF52811_QFAA if BOARD_NRF52840DK_NRF52811선택된 board-target symbol에 따라 SoC symbol이 갈린다. 옛 방식의 설명용 CONFIG_SOC_SERIES_MY_SOC=y와 CONFIG_BOARD_MY_EVB=y 두 줄을 보드 포팅의 완성된 defconfig로 제시하면 이 경계를 놓친다.
3. DTS: SoC와 보드 pinctrl을 포함
Zephyr v3.7.0 고정 원문 boards/nordic/nrf52840dk/nrf52840dk_nrf52840.dts 7–9행
/dts-v1/;
#include <nordic/nrf52840_qiaa.dtsi>
#include "nrf52840dk_nrf52840-pinctrl.dtsi"4. DTS: console의 실제 node 연결
Zephyr v3.7.0 고정 원문 boards/nordic/nrf52840dk/nrf52840dk_nrf52840.dts 16–18행
chosen {
zephyr,console = &uart0;
zephyr,shell-uart = &uart0;선택된 보드 DTS는 SoC 정의를 포함하고 chosen 및 핀 설정을 보드에 맞춘다. 같은 파일의 120–133행에는 샘플에 쓰는 LED와 버튼 alias도 있다. 원본 DTS만 보지 말고 최종 zephyr.dts에서 overlay까지 반영된 값을 확인한다.
5. defconfig: 보드 기본 설정 조각
Zephyr v3.7.0 고정 원문 boards/nordic/nrf52840dk/nrf52840dk_nrf52840_defconfig 12–20행
# enable GPIO
CONFIG_GPIO=y
# enable uart driver
CONFIG_SERIAL=y
# enable console
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=yGPIO·UART·console 설정은 기본값을 더하는 조각이다. 공식 지침에 따르면 공통 defconfig와 qualifier별 defconfig가 있으면 일치하는 조각을 함께 병합한다.
6. board.cmake: flash/debug runner
Zephyr v3.7.0 고정 원문 boards/nordic/nrf52840dk/board.cmake 3–8행
board_runner_args(jlink "--device=nRF52840_xxAA" "--speed=4000")
board_runner_args(pyocd "--target=nrf52840" "--frequency=4000000")
include(${ZEPHYR_BASE}/boards/common/nrfjprog.board.cmake)
include(${ZEPHYR_BASE}/boards/common/nrfutil.board.cmake)
include(${ZEPHYR_BASE}/boards/common/jlink.board.cmake)
include(${ZEPHYR_BASE}/boards/common/pyocd.board.cmake)board_runner_args와 공통 runner 포함은 west flash/debug를 위한 정보다. 이를 제거하면 빌드 대상 자체가 사라진다고 설명해서는 안 된다.
원본을 추적하는 순서
board.yml에서 대상 보드 이름과 허용 SoC·variant·revision을 본다. 먼저 SoC 자체가 v3.7.0에서 지원되는지 확인한다.-b nrf52840dk/nrf52840의 qualifier와 일치하는Kconfig.nrf52840dk, 보드 DTS, defconfig 파일을 찾는다.- 빌드한 뒤
build/zephyr/.config와build/zephyr/zephyr.dts를 열어 최종 선택을 확인한다. 원본 소스와 생성 결과가 다를 수 있다. - flash/debug 문제라면 그때
board.cmake와 runner 환경을 본다. 실제 동작 문제라면 콘솔 출력, 클록과 핀·인터럽트 등 보드 bring-up을 별도로 확인한다.
qualifier, revision, 파일명은 서로 다른 선택이다
공식 문서의 보드 대상 형식은 board name[@revision][/SoC[/CPU cluster][/variant]]이다. SoC가 하나인 단일 코어 보드는 이름만 쓸 수도 있지만, 이 nRF52840 DK처럼 여러 SoC 대상을 선언하면 원하는 qualifier를 명시한다. 슬래시는 대상 이름에 쓰이고, qualifier가 파일명으로 들어갈 때는 밑줄로 정규화된다.
DTS는 후보를 모두 순서대로 실행하지 않는다. 대상에 맞는 가장 구체적인 DTS 파일 하나를 선택한다. 반면 보드 공통 defconfig와 qualifier별 defconfig가 있으면 일치하는 조각을 함께 병합할 수 있다. 두 메커니즘을 똑같은 상태 전이로 그리면 실제 선택 결과를 잘못 읽게 된다.
보드 포팅 파일 계약
| 파일·조건 | v3.7.0 역할 | 필수 여부와 확인법 |
|---|---|---|
| 지원 SoC | CPU/클록/메모리/인터럽트 기반 | 선행 조건. 미지원 SoC라면 보드 디렉터리만으로 해결되지 않는다. |
board.yml | 보드 이름·SoC·variant·선택적 revision | 필수. west boards와 보드 대상 선택을 확인한다. |
board.dts 또는 qualifier별 DTS | 하드웨어, chosen, aliases, pinctrl | 필수. 최종 zephyr.dts를 확인한다. |
Kconfig.<board> | 보드/SoC 선택 | 필수. 최종 .config에서 선택을 확인한다. |
공통·qualifier별 _defconfig | 필요한 기본 software 설정 | 선택. 존재하는 일치 조각의 병합 결과를 확인한다. |
board.cmake | flash/debug runner와 인자 | west build에는 선택, west flash/debug 지원에는 필요하다. |
하나의 상태 머신 대신 단계별 합격 조건을 본다
이 글의 SoC, DTS, defconfig, runner는 같은 객체가 declared → ready → failed로 변하는 상태가 아니다. 각 단계에 남는 증거가 다르다.
| 관문 | 합격을 말할 수 있는 범위 | 아직 보장하지 않는 것 |
|---|---|---|
| 대상 발견 | 보드 이름과 qualifier가 인식됨 | DTS/Kconfig 구성 성공 |
| configure·generate | .config와 zephyr.dts가 생성됨 | 컴파일·링크 완료 |
| 빌드 | firmware image 생성 | runner와 장비 연결 |
| flash/debug | runner가 선택되고 전송 시도/성공 | 콘솔·핀·클록의 실제 동작 |
| bring-up | 기준 샘플의 관측 결과 | 모든 주변장치와 제품 설정 |
실패 조건표: 먼저 어느 관문인지 찾는다
| 증상 | 먼저 볼 증거 | 가능한 경계 | 다음 확인 |
|---|---|---|---|
| 보드 대상이 발견되지 않음 | west boards, board.yml, BOARD_ROOT | 보드 디렉터리 검색과 대상 이름 | 지원 SoC 및 qualifier 표기 비교 |
| 선택한 SoC와 설정이 어긋남 | board.yml, Kconfig.<board>, .config | 대상별 SoC symbol 선택 | 실제 -b qualifier와 조건문 대조 |
| 빌드는 성공하지만 UART/LED가 동작하지 않음 | zephyr.dts, chosen, aliases, pinctrl | 보드 배선·overlay·driver와 runtime | 원본 DTS가 아닌 병합 결과와 하드웨어 관측 비교 |
west flash에서 runner 오류 | board.cmake, west flash --context | runner 설정·도구·probe 연결 | 빌드 오류와 분리해 runner 환경 점검 |
자주 발생하는 잘못된 접근
DTS 한 장이나 예시 defconfig만으로 완성된 보드라고 부르기
v3.7.0에서는 board.yml과 Kconfig.<board>의 대상 계약을 함께 보여야 한다. 임의의 my_evb 예제는 실제 빌드 가능한 대상처럼 제시하지 않는다.
runner를 모든 빌드의 선행 조건으로 만들기
board.cmake는 flash/debug 경계에서 조사한다. 빌드가 통과하고 flash가 실패했다면 서로 다른 관문에서 원인을 찾는다.
원본 DTS·설정만 보고 최종 이미지를 추측하기
Application overlay와 설정 조각이 최종 결과를 바꾼다. source에는 node와 symbol이 있어도 최종 zephyr.dts와 .config에 기대한 값이 없다면 실행 코드부터 고칠 일이 아니다.
Linux와 비교할 때 남겨야 할 경계
두 시스템 모두 devicetree와 Kconfig를 사용하지만, 이 Zephyr 보드 포팅 글에서 중요한 관측점은 애플리케이션과 커널을 특정 보드 대상으로 함께 구성한 빌드 산출물이다. Linux의 일반적인 배포 이미지와 같은 방식으로 런타임 탐색을 전제하면 보드 qualifier와 생성 헤더의 역할을 놓치기 쉽다. Linux에도 built-in 구성과 board-specific 설정이 있으므로 둘을 절대적인 이분법으로 설명하지 않는다.
빌드와 실행 시간 축
| 시간 | 무슨 선택이 일어나는가 | 남는 증거 |
|---|---|---|
| T0 대상 지정 | -b로 이름/qualifier/revision 지정 | 명령행, configure 로그 |
| T1 구성 병합 | 보드 DTS/overlay와 Kconfig/defconfig/application 설정 선택 | zephyr.dts, .config |
| T2 코드 생성·링크 | 생성 헤더와 컴파일 산출물을 image에 배치 | generated headers, zephyr.map, ELF |
| T3 전송 | 선택된 runner가 probe/도구를 통해 image 기록 | west flash 결과 |
| T4 동작 관측 | 콘솔·타이머·GPIO 등 최소 bring-up 검사 | 보드 로그와 실제 입출력 |
nRF52840 DK: 같은 보드 이름에 두 SoC 대상이 있다
고정 원본 board.yml은 nrf52840dk 아래 nrf52840과 nrf52811을 나열한다. v3.7.0 공식 보드 안내는 실제 예제로 west build -b nrf52840dk/nrf52840 samples/hello_world와 west flash를 제시한다. 이 명령은 nrf52840dk_nrf52840.dts와 그 대상에 맞는 Kconfig 및 defconfig를 따라 읽는 출발점이다.
이 DTS의 chosen은 console을 uart0에 연결하고, alias는 샘플의 LED와 버튼 이름을 제공한다. 빌드가 된 뒤 LED가 예상과 다르면 zephyr.dts의 최종 alias와 실제 회로를 함께 확인한다. 이 글은 소스 구조와 진단 순서를 검증했으며, 실제 nRF52840 DK에 flash/run을 수행한 결과를 주장하지 않는다.
추가 확인 사항: 외부 보드와 revision
외부 저장소의 보드는 공식 문서의 BOARD_ROOT 또는 Zephyr module 경로로 검색시킬 수 있다. upstream에 기여할 때의 vendor 하위 디렉터리 규칙과 로컬 보드 폴더 배치는 다를 수 있으므로 배포 위치를 먼저 기록한다. 보드 revision이 있는 경우 board.yml의 revision 규칙과 revision별 overlay/defconfig를 별도 입력으로 검토한다.
SoC·CPU cluster·variant를 모두 쓰는 보드도 있다. 단일 코어 nRF52840 예제만 보고 모든 target 문자열이 두 부분이라고 일반화하지 않는다.
코드 리뷰 확인 사항
board.yml의 이름과 실제-b대상, 지원 SoC가 서로 맞는가?- 선택한 qualifier에 맞는 DTS와 Kconfig 조건이 무엇이며, 공통·qualifier별 defconfig 중 무엇이 병합되는가?
- console, SRAM, flash, LED alias, pinctrl이 실제 회로와 최종
zephyr.dts에서 일치하는가? - 빌드 성공과 flash/debug 지원, 실물 동작 성공을 각각 어떤 증거로 분리했는가?
재현 가능한 확인 명령
다음은 v3.7.0의 공식 nRF52840 DK 예제 대상에 대한 명령이다. 이미 v3.7.0 작업 공간과 toolchain을 갖춘 환경에서 실행한다.
west boards
west build -b nrf52840dk/nrf52840 samples/hello_world
west flash --context
west flash
west boards는 보드 검색, west build는 이미지 생성, west flash --context는 runner 선택 가능성을 확인한다. 마지막 flash 명령은 실제 장비와 도구가 준비된 경우에만 수행한다. 빌드 뒤에는 build/zephyr/.config, build/zephyr/zephyr.dts와 generated headers를 함께 보며, 원본 파일만으로 최종 값을 단정하지 않는다.
실험 기록 양식
[Zephyr source] v3.7.0 / 36940db938a8f4a1e919496793ed439850a221c2
[board target] nrf52840dk/nrf52840 (revision이 있으면 함께 기재)
[board directory / BOARD_ROOT] 경로와 검색 방식
[build] 명령, 성공/실패, .config·zephyr.dts·map 보존 위치
[flash] runner, probe, 명령, 성공/실패 또는 미실시
[run] console, timer, LED/button 관찰 결과 또는 미실시
[difference] 원본 입력과 생성 산출물의 차이
Zephyr revision과 생성 산출물을 함께 남겨야 나중에 같은 보드 구성을 재현할 수 있다. 빌드가 성공했어도 flash/run을 하지 않았다면 명확히 미실시로 기록한다.
주요 용어
| 용어 | 이 글에서의 뜻 |
|---|---|
| board name | board.yml이 선언한 보드 이름 |
| board target | 보드 이름에 선택적 revision과 SoC/CPU cluster/variant qualifier를 더한 빌드 선택값 |
| qualifier | 같은 보드 디렉터리에서 SoC 또는 세부 실행 대상을 고르는 접미 경로 |
| defconfig | 최종 Kconfig에 병합될 보드 기본 설정 조각; runtime 상태가 아님 |
| runner | west flash/debug가 외부 전송·디버그 도구를 호출하는 연결부 |