SoC 포팅: 보드 아래의 하드웨어 계약은 어디에 있을까?

1. family·series·SoC·cluster와 보드 변형은 다른 층이다

hardware model v2의 계층은 family → series → SoC → CPU cluster → CPU core/architecture다. family·series는 선택 사항이며, 보드는 하나 이상의 SoC를 담을 수 있다. ns 같은 variant는 이 계층의 새 칩이나 새 CPU가 아니라 특정 보드 target의 빌드 변형이다. 실제 nRF5340의 soc.yml에는 nordic_nrf family, nrf53 series, nrf5340 SoC와 cpuapp·cpunet cluster가 있다.

board target의 일반형은 board[@revision][/SoC[/CPU cluster][/variant]]다. 한 SoC·단일 cluster 보드는 qualifiers를 생략할 수 있지만, nRF5340 DK에서는 어떤 cluster와 변형을 빌드하는지 적는다. 보드 target 문자열을 soc.yml의 SoC 이름과 혼동하면 이름은 비슷해도 다른 파일을 찾게 된다.

근거: 3.7.0 hardware 계층, board target 문법, Nordic soc.yml, DK board.yml.

2. 칩 하나를 추가할 때 파일 이름보다 책임을 먼저 본다

3.7.0의 실제 Nordic 예시는 일반 가이드의 최소 디렉터리 예시보다 공통 파일을 더 위에서 공유한다. soc.yml과 공통 Kconfig.soc는 soc/nordic/에 있고, nRF53 고유 Kconfig.soc·Kconfig·CMakeLists.txt·soc.c·soc.h는 soc/nordic/nrf53/에 있다. 따라서 예시의 파일을 전부 soc/nordic/nrf53/에 복제하는 식으로 읽으면 실제 선택 경로를 놓친다.

근거: SoC porting 파일 역할, Nordic 공통 Kconfig.soc, nRF53 Kconfig.soc, nRF53 Kconfig.

3. devicetree와 Kconfig는 같은 hardware를 다른 질문으로 읽는다

soc.yml·board.yml은 target을 발견하고 분류하는 메타데이터다. 선택된 target의 DTS 계열은 하드웨어 노드·주소·연결을 표현하고, Kconfig 계열은 그 target에서 컴파일할 소프트웨어 기능을 정한다. soc.h·soc.c는 빌드된 SoC 코드의 별도 경계다. 한 파일의 선언이 다른 계열의 내용을 자동으로 생성한다고 읽지 않는다.

경계: Kconfig.soc는 Zephyr 밖의 sysbuild Kconfig에서도 재사용할 수 있는 SoC 선택 트리여야 한다. nRF53의 Zephyr 전용 Kconfig가 ARM·Cortex-M33·기능 심볼을 고르는 실제 예시다. 보드 전용 기본값이나 애플리케이션 prj.conf로 새로운 SoC의 하드웨어 이름을 대신 만들어내지 않는다.

근거: 3.7.0 SoC Kconfig 분리, board DTS와 include, nRF53 CMakeLists, 앱 설정.

4. 같은 nRF5340이라도 cpuapp·cpunet 이미지는 서로 다르다

board.yml은 SoC nrf5340을 선언하고 ns 변형을 cpuapp에 붙인다. Kconfig.nrf5340dk는 생성된 보드 target 심볼에 따라 SOC_NRF5340_CPUAPP_QKAA 또는 SOC_NRF5340_CPUNET_QKAA를 선택한다. soc/nordic/nrf53/Kconfig.soc는 이 package 심볼을 다시 cluster·series 심볼에 연결하고 SOC="nrf5340" 문자열을 제공한다. 실제 보드 DTS는 선택한 cluster에 맞는 nrf5340_*_qkaa.dtsi를 include한다.

이 세 가지는 build target의 예시이지 지금 이 글에서 실행해 얻은 측정값이 아니다. 개별 이미지의 메모리·주변장치 차이는 source DTS에서 확인했으며, 실제 설정 값은 각 target을 빌드한 뒤 build/zephyr/zephyr.dts와 build/zephyr/.config로 다시 확인해야 한다.

근거: board.yml, board Kconfig, CPUAPP DTS, CPUNET DTS, CPUAPP NS DTS.

5. 새 칩 포팅의 순서는 보드 복사에서 끝나지 않는다

먼저 scripts/list_hardware.py --soc-root=. --socs로 이름 중복을 살피고, 기존 architecture와 CPU core 지원이 있는지 확인한다. 새 ISA·ABI라면 SoC 파일만으로는 초기 부팅·IRQ·context switch를 채울 수 없어 별도 architecture port가 필요하다. 지원되는 아키텍처라면 SoC 메타데이터와 선택 심볼, SoC DTSI, 필요한 SoC 코드·CMake를 만든 다음 보드 쪽 board.yml·Kconfig·DTS가 그 SoC를 가리키게 한다.

트리 밖 정의는 앱 또는 모듈에서 SOC_ROOT, BOARD_ROOT, 필요한 DTS_ROOT를 사용해 발견시킨다. 예를 들어 공식 문서의 형태는 west build -b <board name> -- -DSOC_ROOT=<root> -DBOARD_ROOT=<root>다. 각 root는 해당 soc/·boards/ 디렉터리를 포함하는 상위 디렉터리다. DTSI가 다른 root에 있으면 DTS_ROOT도 제공한다.

v1을 유지하는 경우는 별도 경로다. 3.7 문서는 v2로 변환하는 방법 외에 v3.6의 SoC 정의 자체를 downstream으로 가져와 module 또는 SOC_ROOT에서 발견시키고 구형 board 정의와 함께 쓰는 방법을 허용한다. v1 파일에 soc.yml·board.yml 이름만 붙이는 자동 호환은 없다. 실제 soc/Kconfig도 HWM_SCHEME별 Kconfig 경로를 구분한다. 이 글의 그림과 nRF5340 파일 지도는 v2만 가리킨다.

근거: 새 SoC 구조와 이름 확인, architecture port 계약, 트리 밖 SOC_ROOT·BOARD_ROOT·DTS_ROOT, 3.7 v2 전환 선택지, 3.7 HWM_SCHEME별 Kconfig.

6. 오류 메시지를 만나면 어느 선언까지 도달했는가?

SoC 포팅 실패를 보드 파일 하나에 몰아넣기보다, target 발견 → Kconfig 선택 → DTS 결합 → SoC 초기화의 순서로 관찰한다. 아래 그림은 원인을 단정하는 표가 아니라 첫 조사 지점을 정하는 지도다.

v3.7.0 nRF53의 soc.c는 예를 들어 SYS_INIT(nordicsemi_nrf53_init, PRE_KERNEL_1, 0)으로 SoC 초기화 함수를 등록한다. 이것이 모든 SoC에서 똑같은 함수나 우선순위를 써야 한다는 뜻은 아니다. 초기화 순서는 구현 소스와 설정을 함께 읽는다. 이 글은 소스·문서 분석이며 새 칩의 빌드·실기기 부팅 성공을 주장하지 않는다.

근거: nRF53 SYS_INIT, SoC 발견 스크립트, board 빌드 확인.

7. 고정 버전 근거와 이어 읽기

문서는 Zephyr 3.7.0 공개판, 코드와 파일 이름은 같은 v3.7.0 태그에 고정했다. 일부 최신 문서의 hardware model 세부 형식을 3.7.0에 소급하지 않았다.