Kconfig

Zephyr 3.7.0 LTS3에서 먼저 열 파일

설명: 이 글은 한 파일을 위에서 아래로 베끼는 방식이 아니라, Kconfig를 이해하는 데 필요한 kernel object, macro, generated file, runtime state를 같은 흐름 위에 놓고 읽는다. Zephyr는 빌드 단계에서 많은 결정을 끝내기 때문에 원본 C 파일과 함께 Kconfig, devicetree, linker section, generated header를 같이 봐야 한다.

1. symbol 선언

config MY_DRIVER
        bool "My driver"
        depends on GPIO
        select PINCTRL
        default y if BOARD_MY_EVB

읽는 방법: 이 조각은 단독 기능 설명이 아니라 앞의 그림에서 어느 칸의 상태를 바꾸는지 보면서 읽어야 한다. Zephyr 코드의 많은 macro는 C 함수 호출처럼 보여도 실제로는 section 배치, symbol 생성, compile-time assertion, generated constant 참조를 동시에 수행한다.

2. application 설정

CONFIG_GPIO=y
CONFIG_LOG=y
CONFIG_MY_DRIVER=y
CONFIG_MAIN_STACK_SIZE=2048

읽는 방법: 이 조각은 단독 기능 설명이 아니라 앞의 그림에서 어느 칸의 상태를 바꾸는지 보면서 읽어야 한다. Zephyr 코드의 많은 macro는 C 함수 호출처럼 보여도 실제로는 section 배치, symbol 생성, compile-time assertion, generated constant 참조를 동시에 수행한다.

3. 코드에서 config 조건 사용

#if IS_ENABLED(CONFIG_MY_DRIVER)
        my_driver_submit();
#endif

BUILD_ASSERT(CONFIG_MAIN_STACK_SIZE >= 1024);

읽는 방법: 이 조각은 단독 기능 설명이 아니라 앞의 그림에서 어느 칸의 상태를 바꾸는지 보면서 읽어야 한다. Zephyr 코드의 많은 macro는 C 함수 호출처럼 보여도 실제로는 section 배치, symbol 생성, compile-time assertion, generated constant 참조를 동시에 수행한다.

1단계. public API에서 시작한다

먼저 application이나 driver가 실제로 include하는 header를 본다. 이 단계에서는 함수 body를 찾으려 하지 말고, type과 macro가 어떤 storage와 호출 계약을 요구하는지 확인한다. 많은 Zephyr API는 함수처럼 보여도 static inline, macro, conditional compilation으로 갈라진다.

Kconfig
scripts/kconfig
boards/*/*_defconfig

설명: public header는 사용자에게 보이는 계약이다. 여기서 timeout 인자가 있는지, ISR에서 허용되는지, object를 caller가 제공해야 하는지, return value가 어떤 error domain을 쓰는지 먼저 표시한다.

2단계. macro expansion을 눈으로 풀어 본다

Zephyr의 많은 object는 선언 macro 하나로 끝나지 않는다. 예를 들어 device, thread stack, queue, init entry는 macro가 storage object, metadata, section attribute, alignment를 같이 만든다. 따라서 macro 이름만 보고 "등록된다"라고 넘어가면 실제 binary layout을 놓친다.

/* 읽을 때 머릿속에서 이렇게 풀어 본다 */
DECLARATION_MACRO(name, arg0, arg1)
        -> static storage
        -> metadata structure
        -> linker section placement
        -> generated symbol reference
        -> runtime iterator consumes it

설명: 이 풀이는 실제 C 전처리 결과와 1:1로 같다는 뜻이 아니라, 독해 관점에서 확인할 항목을 나열한 것이다. 필요하면 build/zephyr/include/generated와 map file에서 symbol 이름을 확인한다.

3단계. runtime body로 내려간다

그 다음에야 kernel/, subsys/, drivers/ 아래의 구현 파일로 내려간다. 구현 파일에서는 happy path보다 state check, wait queue, timeout, lock, reference ownership, error return을 먼저 본다. 작은 RTOS에서는 실패 처리 하나가 전체 firmware의 deadline과 recovery 정책을 결정한다.

4단계. build artifact로 되돌아온다

마지막에는 반드시 build directory로 돌아온다. 원본 파일을 읽은 뒤 실제 image에 어떤 symbol이 들어갔는지 확인하지 않으면, 분석은 소스 트리의 가능성만 본 것이다. 제품 firmware는 가능성의 집합이 아니라 특정 configuration 하나의 결과물이다.

build/zephyr/.config
build/zephyr/zephyr.dts
build/zephyr/include/generated/
build/zephyr/zephyr.map
build/zephyr/zephyr.elf

설명: 이 다섯 개가 실제 검증 대상이다. 특히 Kconfig처럼 subsystem boundary가 많은 주제는 원본 C보다 generated output이 더 직접적인 진실을 보여줄 때가 많다.

declared에서 linked로

이 전이는 C 함수 호출이 아니라 build system과 linker가 만든다. macro가 section attribute를 붙이고, linker script가 section을 모으고, map file에 순서가 남는다. 이 단계에서 빠진 object는 런타임에서 절대 찾을 수 없다.

initialized에서 ready로

초기화 함수가 호출되었다고 ready가 되는 것은 아니다. return value, dependency readiness, clock/reset/pinctrl, memory allocation 결과가 모두 맞아야 consumer가 사용할 수 있다. 그래서 device_is_ready(), return code, assert를 습관적으로 본다.

ready에서 failed로 되돌아가는 경우

RTOS에서는 ready 이후에도 runtime failure가 많다. queue full, timeout, workqueue backlog, device suspend, network down, heap exhaustion 같은 사건은 initialized 상태를 지우지 않지만 operation 단위 실패를 만든다. 이 차이를 구분해야 "초기화 문제"와 "운영 중 압력 문제"를 나눌 수 있다.

안티패턴 1. source tree만 보고 최종 image를 안 본다

소스에 함수가 있다는 말은 firmware에 들어갔다는 뜻이 아니다. Kconfig가 끄면 compile unit 자체가 빠질 수 있고, devicetree status가 disabled이면 driver instance가 생성되지 않을 수 있다. 따라서 Kconfig 관련 bug를 볼 때는 source tree보다 build output을 먼저 확인하는 습관이 필요하다.

안티패턴 2. timeout을 디버깅 회피 수단으로 쓴다

K_MSEC(100) 같은 값을 넣고 문제가 사라졌다고 판단하면 안 된다. timeout은 설계 값이어야 한다. producer/consumer 속도, interrupt rate, workqueue backlog, scheduler priority를 계산하지 않고 넣은 timeout은 field에서 더 큰 latency spike로 돌아온다.

안티패턴 3. system workqueue를 개인 thread처럼 쓴다

workqueue는 편하지만 공유 자원이다. 오래 걸리는 handler, blocking I/O, 큰 parsing 작업을 system workqueue에 넣으면 다른 subsystem의 deferred work까지 지연된다. Kconfig가 workqueue를 거친다면 handler 실행 시간과 queue depth를 따로 적어야 한다.

안티패턴 4. stack size를 감으로 키운다

stack overflow가 의심될 때 값을 두 배로 키우는 것은 임시 처치다. call depth, logging 사용, printf formatting, crypto/network path, userspace guard 비용을 따로 봐야 한다. Zephyr에서는 stack watermark와 thread analyzer를 통해 근거 있는 값을 잡는 편이 맞다.

안티패턴 5. ready check를 생략한다

device pointer가 compile-time에 존재한다고 해서 runtime usable 상태라는 뜻은 아니다. init 함수가 실패했거나 provider dependency가 준비되지 않았을 수 있다. 이 실수는 board porting 초기에 특히 자주 나온다.

runtime discovery보다 build-time composition이 강하다

Linux는 bus, driver core, module, sysfs, hotplug처럼 런타임 discovery와 policy가 두껍다. Zephyr도 device model이 있지만, 많은 board에서는 devicetree와 Kconfig가 미리 가능한 세계를 작게 만든다. 그래서 Kconfig 분석에서는 "왜 런타임에 못 찾지?"보다 "빌드 결과에 애초에 들어왔나?"를 먼저 물어야 한다.

메모리와 시간의 upper bound가 더 노골적이다

Zephyr는 flash/RAM이 작은 MCU부터 대상으로 한다. 따라서 queue depth, stack size, slab count, workqueue 처리 시간 같은 값이 설계의 일부다. Linux에서라면 성능 튜닝 항목으로 넘길 수 있는 수치가 Zephyr에서는 correctness 조건이 된다.

debugging은 generated file을 포함한다

원본 C 파일만 보면 절반만 본 것이다. Zephyr는 build/zephyr/zephyr.dts, build/zephyr/.config, generated headers, linker map이 원본 코드 해석의 일부다. 문C식으로 그림과 코드를 나란히 놓을 때도 이 산출물을 한 축으로 넣어야 한다.

시나리오 A. 빌드는 되는데 런타임에서 아무 일도 안 일어난다

첫 번째로 볼 것은 함수 body가 아니라 빌드 산출물이다. Kconfig symbols 단계가 source에는 있어도 최종 image에 들어가지 않았을 수 있다. Kconfig가 꺼져 있거나, devicetree node가 disabled이거나, macro expansion 조건이 맞지 않으면 C 파일을 아무리 읽어도 실행 지점에 도달하지 않는다.

grep -n "CONFIG_" build/zephyr/.config
grep -n "status = \"okay\"" build/zephyr/zephyr.dts
grep -n "Kconfig" build/zephyr/zephyr.map

설명: 이 세 줄은 source, hardware description, linker 결과를 한 번에 확인한다. Zephyr에서는 이 셋이 맞아야 원본 코드가 실제 firmware 동작으로 이어진다.

시나리오 B. 한 번은 동작하고 두 번째부터 멈춘다

이 경우에는 lifetime과 ownership을 먼저 의심한다. stack에 둔 object 주소를 workqueue나 ISR이 나중에 사용하거나, static object라고 생각한 buffer가 실제로는 producer가 다시 덮어쓰는 scratch buffer일 수 있다. Kconfig에서는 특히 "누가 object를 소유하고 언제 넘기는가"가 중요하다.

시나리오 C. latency가 간헐적으로 튄다

평균 latency가 아니라 tail latency를 본다. RTOS에서 문제는 "대체로 빠르다"가 아니라 "가끔 deadline을 넘는다"인 경우가 많다. interrupt, scheduler, workqueue, heap allocation, logging이 섞이면 간헐적인 긴 구간이 생긴다. Kconfig를 분석할 때는 context 전환과 timeout queue를 시간 축 위에 표시한다.

uint32_t t0 = k_cycle_get_32();
critical_path();
uint32_t dt = k_cycle_get_32() - t0;
LOG_INF("critical path cycles=%u", dt);

설명: 단순 로그도 처음에는 충분하다. 이후에는 tracing backend나 board counter를 붙여 ISR entry, work submit, thread wake-up 사이 간격을 따로 잰다.

시나리오 D. 설정 하나 바꿨더니 전혀 다른 subsystem이 깨진다

Zephyr에서는 Kconfig symbol 하나가 code size, stack size, device dependency, logging path, userspace permission을 동시에 바꿀 수 있다. 설정 변경 뒤에는 source diff만 볼 것이 아니라 .config, zephyr.dts, map file의 변화를 같이 봐야 한다. 작은 RTOS일수록 build-time composition의 파급이 크다.

cp build/zephyr/.config before.config
west build -p auto -b <board> <app>
diff -u before.config build/zephyr/.config

설명: 변경 전후의 최종 설정을 비교하면, 내가 직접 바꾼 symbol이 아닌 간접 dependency가 드러난다.

1. 결정성 determinism

이 경로의 worst-case execution time은 어디서 결정되는가. interrupt disable 구간, spinlock 보유 시간, ready queue scan, memory allocation, logging backend가 upper bound를 흐리게 만들지는 않는가. Kconfig의 각 API는 평균 비용보다 최악 비용을 먼저 적어야 한다.

Zephyr LTS를 쓰는 이유도 여기와 맞닿아 있다. 장기 지원 branch에서는 API와 내부 정책 변화가 줄어들어, 측정한 worst-case가 제품 수명 동안 유지될 가능성이 높아진다. 최신 stable을 따라가는 실험 branch와 LTS product branch를 분리해 분석하는 편이 좋다.

2. memory footprint와 fragmentation

정적 object는 예측 가능하지만 낭비가 생길 수 있고, 동적 object는 평균 footprint를 줄일 수 있지만 fragmentation과 allocation latency를 만든다. Kconfig에서 buffer, queue, stack, slab, heap 중 무엇을 쓰는지에 따라 실패 모드가 달라진다.

분석할 때는 RAM 총량이 아니라 peak 동시 사용량을 본다. ISR burst, network burst, workqueue backlog, nested callback이 겹치는 순간을 worst-case scenario로 잡고, 그때 object 수와 stack depth가 버티는지 계산한다.

3. isolation과 fault containment

userspace, memory domain, MPU, stack guard, assertion은 모두 비용이 있다. 하지만 제품에서 한 driver의 pointer bug가 전체 firmware를 망가뜨리지 않게 하려면 isolation boundary가 필요하다. Kconfig를 읽을 때도 기능이 아니라 fault containment 관점으로 다시 그릴 수 있어야 한다.

이 관점에서는 "성공 경로가 빠른가"보다 "실패했을 때 어디서 멈추고 어떤 정보를 남기는가"가 중요하다. panic, fatal error, assert, return code, log level을 하나의 정책으로 맞추는 것이 필요하다.

4. Linux와 다른 검증 방식

Linux kernel은 dynamic workload와 복잡한 runtime policy를 견디도록 설계되어 있다. Zephyr는 더 작은 구성 공간을 전제로 compile-time 결정을 적극적으로 사용한다. 따라서 검증도 runtime fuzzing만이 아니라 configuration matrix와 generated artifact diff가 중요하다.

예를 들어 board A와 board B가 같은 application source를 쓰더라도 devicetree와 Kconfig가 다르면 실제 image는 전혀 다른 system이 된다. 이 차이를 source-level review만으로 잡으려 하면 놓치는 것이 많다.

configuration 질문

• 이 기능이 켜지는 Kconfig symbol은 무엇이며, hidden dependency가 있는가.
• board defconfig와 application prj.conf 중 어느 쪽이 최종 값을 결정하는가.
• 설정이 꺼졌을 때 compile error가 나는가, 조용히 기능이 빠지는가.
• LTS branch에서 이 symbol의 default나 dependency가 stable하다고 볼 수 있는가.

devicetree 질문

• consumer가 참조하는 node가 최종 merged DTS에서 status = "okay"인가.
• alias/chosen을 쓰는 경우 board별 override가 의도대로 적용되는가.
• binding property 이름과 C macro 이름이 정확히 대응하는가.
• pinctrl, clock, reset, interrupt property가 provider driver 초기화보다 늦게 소비되지 않는가.

concurrency 질문

• 이 API는 ISR에서 호출 가능한가. 가능하다면 내부에서 sleep하지 않는가.
• 공유 object는 mutex, spinlock, atomic, workqueue serialization 중 무엇으로 보호되는가.
• timeout은 정상적인 backpressure인가, 장애를 감추는 임시방편인가.
• priority inversion이 생겼을 때 상한을 계산할 수 있는가.

operability 질문

• 실패했을 때 return code와 log가 원인을 구분할 만큼 남는가.
• assert를 끈 production build에서도 복구 또는 안전 정지가 가능한가.
• stack, heap, slab, queue 사용량을 계측할 방법이 있는가.
• Kconfig가 깨졌을 때 field engineer가 확인할 수 있는 최소 로그는 무엇인가.

빌드 결과 확인

west build -b <board> <app>
grep CONFIG_ build/zephyr/.config
grep -n "<node-or-compatible>" build/zephyr/zephyr.dts

설명: Kconfig가 기대하는 symbol과 node가 최종 build에 들어왔는지 먼저 본다. source tree의 DTS/Kconfig 원본이 아니라 build directory의 merged 결과가 기준이다.

런타임 관찰

CONFIG_LOG=y
CONFIG_ASSERT=y
CONFIG_THREAD_NAME=y
CONFIG_INIT_STACKS=y

설명: 로그와 assert는 footprint 비용이 있지만 bring-up 단계에서는 시간을 아낀다. thread 이름, stack 초기화, assert를 켜면 잘못된 context 호출이나 stack 부족이 훨씬 빨리 드러난다.

실험 과제

• Kconfig에서 사용하는 object 하나를 의도적으로 disabled 상태로 만들고 어떤 build/runtime 에러가 나는지 본다.
• timeout을 K_NO_WAIT, K_MSEC(1), K_FOREVER로 바꿔 latency와 실패 양상이 어떻게 달라지는지 기록한다.
• map file 또는 generated header에서 이 글의 원본 코드 조각이 어떤 symbol로 남는지 확인한다.

읽는 순서

처음에는 API 이름을 외우지 말고, Kconfig 근처에서 시작해 빌드 산출물과 runtime object를 왕복한다. 그 다음 같은 기능을 enabled/disabled로 바꿔 보고, 어떤 symbol과 section이 사라지는지 확인한다. 마지막으로 timeout과 priority를 바꿔 latency가 어떻게 달라지는지 측정한다.

이 과정을 한 번 거치면 Kconfig가 단순 기능 묶음이 아니라, 제한된 RAM과 deadline 안에서 어떤 불변조건을 지키려는 설계인지 보이기 시작한다. 그 지점부터 원본 코드의 macro와 작은 helper 함수들이 의미를 갖는다.