Barebox · source analysis

State framework와 영속 변수

DT로 정의한 typed variable을 storage backend에서 읽고 여러 저장본의 검증·갱신으로 영속화하는 state framework를 분석합니다.

표의 버전은 소스 분석 기준이며 최신 보안 버전 권고가 아닙니다. 제품 적용 시 사용 플랫폼의 errata를 확인하세요.

Series
12 / 19
Baseline
v2026.06.1
Commit
314c679eea2d
Source
common/state/state.c:20-108 (발췌 범위)

State framework와 영속 변수 단계에서 실제로 바뀌는 상태는 무엇인가?

environment와 제품 상태를 구분한다. attempts, priority 같은 값의 type/width와 redundant/circular backend가 전원 차단을 견디는 방식을 본다.

저장 중 전원이 끊겨도 읽을 수 있는 copy가 남는지는 bucket 쓰기 순서와 저장 매체에 달려 있다. 저장 성공 반환, 재부팅 후 첫 유효 copy 선택, 복구 쓰기를 각각 구분해 확인한다.

객체와 주소가 놓이는 구조

그림 1. State framework와 영속 변수에서 입력, 내부 상태, 출력의 경계
입력과 전제내부 상태외부로 공개되는 결과
01state object
02typed variables
03backend format
04redundant buckets

struct state / state backend buckets를 중심에 놓고 왼쪽의 입력이 어떤 검사를 거쳐 오른쪽 결과로 공개되는지 표시했다. 실제 디버깅에서는 각 블록의 주소와 크기를 로그에 대입한다.

state 저장의 주요 호출

그림 2. state_save()에서 bucket write까지
dirty state
format->pack
storage_write
bucket->write × N
dirty = 0

state_save()는 dirty일 때만 pack하고 등록된 모든 bucket에 순서대로 쓰기를 시도한다. 쓰기 가능한 backend에서는 최소 1개 bucket 쓰기가 성공하면 dirty를 지운다. 실패한 bucket이 있어도 이 기준을 충족하면 성공하며, readonly storage는 쓰지 않고 0을 반환한다.

단계별 입력과 출력

고정 v2026.06.1의 저장·재읽기 경로를 구분했다. 성공 기준과 검증 방식은 backend format 및 bucket 종류에 따라 확인한다.

#단계진입 시 신뢰할 상태성공 뒤 남아야 할 상태다음 소비자
01state_save()dirty인 typed state 값format->pack 호출dirty가 아니면 저장 없이 0 반환
02format->packDT가 정의한 변수와 backend format하나의 packed bufferraw는 header/data CRC, dtb는 flattened DTB
03state_storage_write()packed buffer와 등록된 bucket 목록모든 bucket의 write 시도목록 순서가 재부팅 후 읽기 우선순위
04bucket->write각 bucket의 직접 또는 circular 저장 영역성공/실패 횟수쓰기 가능 시 최소 성공 1개; readonly는 write 생략
05state_storage_read()재부팅 후 각 bucket의 bytes형식 검증을 통과한 첫 copy다른 bucket을 refresh한 뒤 unpack

분석 범위의 전제와 비교해, 다음 단계에 잘못된 입력을 넘긴 부분부터 조사한다.

쓰기 순서와 재부팅 후 선택을 그림으로 읽기

아래 경로는 메모리 주소 지도가 아니라 state backend의 저장·복구 절차다. 실제 bucket 개수와 offset은 보드의 state backend 설정 및 로그로 확인한다.

그림 3. 모든 bucket 순차 쓰기와 첫 유효 copy 복구

v2026.06.1의 쓰기 가능한 backend 경로다. 숫자는 하나의 저장과 뒤이은 재읽기를 잇는다.

01dirty + pack
02각 bucket 순차 write
03성공 ≥ 1?
04재부팅: 첫 valid
05다른 copy refresh
그림 4. 환경 파일과 state variable

두 열의 객체는 이름이 비슷해도 생성 시점, 사용 가능한 API와 해제 책임이 다르다.

Environment

01문자열·script 중심

02사용자 편집

03directory overlay

04saveenv 단위

05boot policy 입력

State

01DT typed schema

02고정 width

03redundant bucket

04format별 검증

05attempts·priority

원본 코드

아래 코드는 Barebox v2026.06.1의 common/state/state.c에서 20-108줄을 그대로 가져온 것이다.

commit314c679eea2d0ca847c64d1b646a1cf91225c0ecanchor · L44int state_save(struct state *state)
20#include <errno.h>
21#include <fs.h>
22#include <crc.h>
23#include <init.h>
24#include <block.h>
25#include <linux/err.h>
26#include <linux/list.h>
27#include <linux/uuid.h>
28
29#include <linux/mtd/mtd-abi.h>
30#include <malloc.h>
31#include <state.h>
32#include <libbb.h>
33
34#include "state.h"
35
36/* list of all registered state instances */
37static LIST_HEAD(state_list);
38
39/**
40 * Save the state
41 * @param state
42 * @return
43 */
44int state_save(struct state *state)
45{
46	void *buf;
47	ssize_t len;
48	int ret;
49	struct state_backend_storage_bucket *bucket;
50	struct state_backend_storage *storage;
51
52	if (!state->dirty)
53		return 0;
54
55	ret = state->format->pack(state->format, state, &buf, &len);
56	if (ret) {
57		dev_err(&state->dev, "Failed to pack state with backend format %s, %d\n",
58			state->format->name, ret);
59		return ret;
60	}
61
62	storage = &state->storage;
63	if (state->keep_prev_content) {
64		bool has_content = 0;
65		list_for_each_entry(bucket, &storage->buckets, bucket_list)
66			has_content |= bucket->wrong_magic;
67		if (has_content) {
68			dev_err(&state->dev, "Found foreign content on backend, won't overwrite.\n");
69			ret = -EPERM;
70			goto out;
71		}
72	}
73
74	ret = state_storage_write(storage, buf, len);
75	if (ret) {
76		dev_err(&state->dev, "Failed to write packed state, %d\n", ret);
77		goto out;
78	}
79
80	state->dirty = 0;
81
82out:
83	free(buf);
84	return ret;
85}
86
87/**
88 * state_do_load - Loads a state from the backend
89 * @param state The state that should be updated to contain the loaded data
90 * @return 0 on success, -errno on failure. If no state is loaded the previous
91 * values remain in the state.
92 *
93 * This function uses the registered storage backend to read data. All data that
94 * we read is checked for integrity by the formatter. After that we unpack the
95 * data into our state.
96 */
97static int state_do_load(struct state *state, enum state_flags flags)
98{
99	void *buf = NULL;
100	ssize_t len;
101	int ret;
102
103	ret = state_storage_read(&state->storage, state->format,
104				 state->magic, &buf, &len, flags);
105	if (ret) {
106		dev_err_state_init(&state->dev, ret, "format %s read failed\n",
107				   state->format->name);
108		goto out;

발췌 범위와 읽기 기준

원문 20-108줄에는 앞뒤 문맥이 포함됩니다. 기준 구문 int state_save(struct state *state)은 L44에 있습니다. 발췌 첫 줄을 함수 정의의 시작으로 해석하지 않습니다.

environment와 제품 상태를 구분한다. attempts, priority 같은 값의 type/width와 redundant/circular backend가 전원 차단을 견디는 방식을 본다.

함께 읽어야 하는 원본 코드

첫 코드 조각만으로 동작이 완성되지 않는 경우 호출 매크로, 객체 정의와 실제 실행 목록을 같은 페이지에 묶었다. 각 조각은 같은 기준 commit에서 가져왔다.

01. backend에서 state를 읽고 typed variable에 반영

common/state/state.c 87-169줄이다.

filecommon/state/state.canchor · L97static int state_do_load
87/**
88 * state_do_load - Loads a state from the backend
89 * @param state The state that should be updated to contain the loaded data
90 * @return 0 on success, -errno on failure. If no state is loaded the previous
91 * values remain in the state.
92 *
93 * This function uses the registered storage backend to read data. All data that
94 * we read is checked for integrity by the formatter. After that we unpack the
95 * data into our state.
96 */
97static int state_do_load(struct state *state, enum state_flags flags)
98{
99	void *buf = NULL;
100	ssize_t len;
101	int ret;
102
103	ret = state_storage_read(&state->storage, state->format,
104				 state->magic, &buf, &len, flags);
105	if (ret) {
106		dev_err_state_init(&state->dev, ret, "format %s read failed\n",
107				   state->format->name);
108		goto out;
109	}
110
111	ret = state->format->unpack(state->format, state, buf, len);
112	if (ret) {
113		dev_err(&state->dev, "Failed to unpack read data with format %s although verified, %d\n",
114			state->format->name, ret);
115		goto out;
116	}
117
118	state->init_from_defaults = 0;
119out:
120	state->dirty = !!ret; /* mark dirty on error */
121	free(buf);
122	return ret;
123}
124
125int state_load(struct state *state)
126{
127	return state_do_load(state, 0);
128}
129
130int state_load_no_auth(struct state *state)
131{
132	return state_do_load(state, STATE_FLAG_NO_AUTHENTICATION);
133}
134
135static int state_format_init(struct state *state, const char *backend_format,
136			     struct device_node *node, const char *state_name)
137{
138	int ret;
139
140	if (!backend_format || !strcmp(backend_format, "raw")) {
141		ret = backend_format_raw_create(&state->format, node,
142						state_name, &state->dev);
143	} else if (!strcmp(backend_format, "dtb")) {
144		ret = backend_format_dtb_create(&state->format, &state->dev);
145	} else {
146		dev_err(&state->dev, "Invalid backend format %s\n",
147			backend_format);
148		return -EINVAL;
149	}
150
151	if (ret && ret != -EPROBE_DEFER)
152		dev_err(&state->dev, "Failed to initialize format %s, %d\n",
153			backend_format, ret);
154
155	return ret;
156}
157
158static void state_format_free(struct state_backend_format *format)
159{
160	if (!format)
161		return;
162
163	if (format->free)
164		format->free(format);
165}
166
167void state_backend_set_readonly(struct state *state)
168{
169	state_storage_set_readonly(&state->storage);

내부 동작을 더 깊게 읽기

01

진입 조건을 먼저 고정한다

DT state node에서 들어온 실행은 부트 CPU의 동기 실행 문맥에 놓여 있다. 이때 interrupt, MMU/cache, stack, heap 중 무엇이 이미 준비되었는지 소스의 호출자까지 올라가 확인한다. 같은 함수라도 SPL, relocation 전후, app thread처럼 호출 문맥이 달라지면 허용되는 API와 지연 시간이 달라진다.

environment와 제품 상태를 구분한다. attempts, priority 같은 값의 type/width와 redundant/circular backend가 전원 차단을 견디는 방식을 본다.

02

중심 객체의 생성과 공개를 나눈다

이 글의 중심 객체는 struct state / state backend buckets다. 메모리를 확보한 시점, 필드를 채운 시점, 전역 list나 다른 subsystem에 공개한 시점을 구분한다. 공개 뒤 오류가 발생한다면 목록에서 제거하고 child, buffer, reference를 역순으로 정리하는지 확인한다.

빌드 산출물 관점에서는 최종 부트로더 이미지 안에 해당 symbol과 section이 실제로 포함되었는지도 map과 objdump로 검증한다.

03

주소, 크기와 정렬을 계산한다

부트 코드에서는 주소 계산 오류를 주의해야 한다. 원본과 목적지의 주소 범위, 헤더에 기록된 데이터 크기, 블록·페이지 단위를 표로 정리하고 각 구간의 끝 주소를 계산한다. 끝 주소가 start + size - 1처럼 마지막 바이트를 가리키는지, 구간 바로 다음 주소를 가리키는지는 API 규약에서 확인한다.

04

성공 flag와 실제 완료 시점을 맞춘다

state variables → pack format → storage buckets 구간에서는 부분 초기화 상태가 생길 수 있다. flag, list insertion, callback 등록, storage write 완료 중 무엇이 성공의 기준인지 찾는다. hardware write나 DMA가 포함되면 함수 반환과 장치 완료가 같은 시점인지도 확인한다.

다른 CPU, 인터럽트 처리기, USB 완료 콜백, 셸 명령에서도 이 상태를 읽는다면 메모리 접근 순서와 잠금 범위를 함께 확인한다.

05

제어권을 넘기기 전에 확인할 조건을 정리한다

정상 경로는 persistent copy에서 끝난다. 이 단계가 함수 반환인지, scheduler 전환인지, 다른 image로의 비복귀 분기인지 구분한다. 비복귀 handoff라면 cache clean/invalidate, interrupt disable, 장치 quiesce, argument register와 FDT 또는 image address가 최종 점검 항목이다.

호출한 함수로 돌아오는 경로라면 오류와 일부 처리만 완료된 상태를 구분하는지 확인한다. 이어서 다음 후보를 시도할지, 복구 절차를 실행할지 살펴본다.

구현을 읽을 때 놓치기 쉬운 부분

01

state variable은 DT가 정의한 type 계약을 가진다

name, type, width, enum과 default가 DT node에서 객체로 만들어지고 backend byte layout과 연결된다. signedness와 endian, field offset을 바꾸면 기존 persistent data와 호환되지 않을 수 있다.

DT schema 변경 시 version과 migration 정책을 둔다.

02

bucket 선택은 목록 순서와 형식 검증을 따른다

state_storage_read()는 목록 순서대로 bucket을 읽고 format 검증을 통과한 첫 copy를 고른다. raw format은 header·data CRC와 선택적 HMAC을 확인하지만, DTB format에는 같은 raw CRC header가 없다. circular bucket의 trailing magic·length는 쓰기 영역 메타데이터이며 generation counter가 아니다.

각 write phase에 reset을 주입해 selection 결과를 표로 만든다.

03

runtime 변경과 durable commit을 구분한다

command로 variable을 바꿔도 state_save()가 성공하기 전에는 RAM 값일 뿐이다. attempts 감소처럼 boot 정책에 쓰는 값은 handoff 전에 storage flush까지 끝나야 한다.

save 실패가 caller에 전달되는지와 재부팅 시 어느 bucket이 선택되는지 확인한다. 최소 1개 write 성공으로 함수가 성공할 수 있으므로 모든 copy가 갱신됐다고 가정하지 않는다.

객체와 수명

대상만들어지는 시점유효 범위확인할 조건
struct state / state backend bucketsstate variablespersistent copy 또는 오류 정리 완료까지진입 전제와 상태 계약
입력 buffer / metadataDT state nodeparse와 검증이 끝날 때까지길이, 정렬, 소유권, 변조 가능성
등록된 list / descriptorpack format하위 시스템을 종료하거나 다음 이미지에 제어권을 넘길 때까지중복 등록, 해제된 객체를 가리키는 포인터, 오류 후 자원 정리
hardware 또는 persistent state실제 write/probe가 완료된 뒤reset 또는 명시적 해제·갱신까지쓰기 완료, 시간 초과, 전원 차단, 이전 상태 복원
최종 부트로더 이미지link/image 생성 시점다음 stage가 새 image로 교체할 때까지적재 주소, 진입점, 섹션, 헤더의 일치 여부

실패 지점과 증상

#조건관찰되는 증상먼저 볼 단계
01DT type 불일치값 truncationstate variables
02선두 bucket 손상다음 형식 유효 copy 선택 또는 유효 copy 없음storage read·format verify
03write 중 resetcopy별 부분 write·검증 실패 가능bucket write·read 순서

로그가 끊긴 함수뿐 아니라 그 함수에 주소, 크기, 플래그를 전달한 앞 단계도 조사한다. 오류 처리 후 등록된 객체나 하드웨어 설정이 그대로 남아 있는지도 확인한다.

소스 밖에서 확인할 증거

소스에서 파악한 동작을 실제 빌드 결과와 대상 보드의 로그로 확인한다. 아래 명령의 보드 이름과 툴체인 접두사는 사용 중인 빌드 환경에 맞게 바꾼다.

#목적명령 또는 계측판정 기준
01빌드 구성make <board>_defconfig && make V=1Kconfig, linker section과 최종 barebox image 생성 명령을 보관한다.
02symbol과 section${CROSS_COMPILE}nm -n barebox | grep 'state_save'initcall, command, driver descriptor가 image에 남았는지 확인한다.
03주소와 resourceiomemimage, malloc, stack, device resource와 reserved 영역의 겹침을 확인한다.
04device 상태devinfo; drvinfo; of_dumpDT node 생성, device 등록, driver probe를 서로 구분한다.
05boot 정책boot -d -v; state -dentry 탐색 결과와 persistent state가 실제 선택에 미친 영향을 확인한다.

직접 확인할 실험

  1. 01
    state -d로 variable과 backend 확인

    state variables 진입 전후에 state object의 주소·크기·반환값과 timestamp를 함께 남긴다.

  2. 02
    저장 중 reset 주입 후 이전/새 copy 선택 확인

    pack format 진입 전후에 typed variables의 주소·크기·반환값과 timestamp를 함께 남긴다.

  3. 03
    DT default와 저장값 우선순위 비교

    storage buckets 진입 전후에 backend format의 주소·크기·반환값과 timestamp를 함께 남긴다.

원문과 다음 글