QUESTION
envfs load와 default environment 단계에서 실제로 바뀌는 상태는 무엇인가?
U-Boot의 key-value blob과 달리 Barebox 환경은 파일과 script 중심이다. 저장 image의 CRC와 entry별 직접 파일 쓰기, 부팅 시 default overlay 순서를 확인한다.
부팅에서는 built-in default environment를 먼저 읽고 외부 envfs를 /env에 추가한다. 전체 CRC 검증은 파일 쓰기보다 앞서지만, entry 처리나 쓰기 중 오류가 나면 앞서 덮은 파일이 남을 수 있다.
STRUCTURE
객체와 주소가 놓이는 구조
envfs_super / environment directory를 중심에 놓고 왼쪽의 입력이 어떤 검사를 거쳐 오른쪽 결과로 공개되는지 표시했다. 실제 디버깅에서는 각 블록의 주소와 크기를 로그에 대입한다.
CALL PATH
envfs_load()의 파일 적용 경로
envfs_load()는 superblock과 전체 data CRC를 검사한 뒤 envfs_load_data()를 호출한다. 이 경로에는 압축 해제나 임시 directory 교체가 없다. force-builtin flag는 별도로 defaultenv_load()를 호출한다.
STATE LEDGER
단계별 입력과 출력
고정 v2026.06.1의 부팅 기본 환경, envfs 이미지 검증, 대상 파일 쓰기를 구분한다. 전체 CRC 성공은 개별 파일 쓰기의 원자성을 뜻하지 않는다.
| # | 단계 | 진입 시 신뢰할 상태 | 성공 뒤 남아야 할 상태 | 다음 소비자 |
|---|---|---|---|---|
| 01 | startup.c | CONFIG_DEFAULT_ENVIRONMENT | built-in default 파일을 /env에 load | 외부 envfs autoload는 설정에 따라 후속 |
| 02 | envfs_load() | 외부 envfs file/cdev | superblock magic·CRC·size 확인 | force-builtin flag면 defaultenv_load 분기 |
| 03 | envfs_check_data() | 읽어 온 image data | 전체 data CRC 검증 | 실패하면 파일 적용 전에 반환 |
| 04 | envfs_load_data() | 각 inode name·mode·content | 대상 경로에 symlink 또는 O_TRUNC 파일 쓰기 | 기존 파일을 entry별로 즉시 변경 |
| 05 | envfs_load() 반환 | entry 처리 결과 | 0 반환만으로 모든 entry 성공을 보증하지 않음 | 후반 entry 오류 시 앞선 변경의 rollback 없음 |
분석 범위의 전제와 비교해, 다음 단계에 잘못된 입력을 넘긴 부분부터 조사한다.
VISUAL WALKTHROUGH
CRC 검증과 파일 변경 시점을 그림으로 읽기
아래 그림은 메모리 주소가 아니라 외부 envfs image를 /env에 적용하는 순서다. CRC 검증 전과 첫 파일 변경 뒤의 오류 결과가 다르다.
고정 environment.c와 envfs-core.c의 load 경로다. defaultenv_load()는 부팅 초기화 또는 force-builtin flag의 별도 분기다.
두 열의 객체는 이름이 비슷해도 생성 시점, 사용 가능한 API와 해제 책임이 다르다.
Default
01binary에 포함
02복구 기준
03build-time 원본
04build version 의존
05부팅 시 먼저 load
Persistent
01storage image
02사용자 수정
03saveenv 결과
04전원 차단 위험
05default 위에 적용
UPSTREAM SOURCE
원본 코드
아래 코드는 Barebox v2026.06.1의 common/environment.c에서 422-510줄을 그대로 가져온 것이다.
422 defenv_path = default_environment_path_get();
423 if (defenv_path && !strcmp(filename, defenv_path))
424 nv_var_set_clean();
425#endif
426out:
427 close(envfd);
428out1:
429 free(buf);
430#ifdef __BAREBOX__
431 unlink_recursive(TMPDIR, NULL);
432#endif
433 return ret;
434}
435EXPORT_SYMBOL(envfs_save);
436
437/**
438 * Restore the last environment into the current one
439 * @param[in] filename from where to restore
440 * @param[in] dir where to store the last content
441 * @return 0 on success, anything else in case of failure
442 *
443 * Note: This function will also be used on the host! See note in the header
444 * of this file.
445 */
446int envfs_load(const char *filename, const char *dir, unsigned flags)
447{
448 struct envfs_super super;
449 void *buf = NULL, *rbuf;
450 int envfd;
451 int ret = 0;
452 size_t size, rsize;
453 __maybe_unused const char *defenv_path;
454
455#ifdef __BAREBOX__
456 if (!IS_ALLOWED(SCONFIG_ENVIRONMENT_LOAD))
457 return -EPERM;
458#endif
459
460 if (!filename)
461 filename = default_environment_path_get();
462 if (!filename)
463 return -ENOENT;
464
465 if (!dir)
466 dir = "/env";
467
468 envfd = open(filename, O_RDONLY);
469 if (envfd < 0) {
470 printf("environment load %s: %m\n", filename);
471 if (errno == ENOENT)
472 printf("Maybe you have to create the partition.\n");
473 return -1;
474 }
475
476 /* read superblock */
477 ret = read(envfd, &super, sizeof(struct envfs_super));
478 if ( ret < sizeof(struct envfs_super)) {
479 perror("read");
480 ret = -errno;
481 goto out;
482 }
483
484 ret = envfs_check_super(&super, &size);
485 if (ret)
486 goto out;
487
488 if (super.flags & ENVFS_FLAGS_FORCE_BUILT_IN) {
489 printf("found force-builtin environment, using defaultenv\n");
490 ret = defaultenv_load(dir, 0);
491 if (ret)
492 printf("failed to load default environment: %s\n",
493 strerror(-ret));
494 goto out;
495 }
496
497 buf = xmalloc(size);
498
499 rbuf = buf;
500 rsize = size;
501
502 while (rsize) {
503 ssize_t now;
504
505 now = read(envfd, rbuf, rsize);
506 if (now < 0) {
507 perror("read");
508 ret = -errno;
509 goto out;
510 }
READING CONTRACT
발췌 범위와 읽기 기준
원문 422-510줄에는 앞뒤 문맥이 포함됩니다. 기준 구문 int envfs_load(const char *filename은 L446에 있습니다. 발췌 첫 줄을 함수 정의의 시작으로 해석하지 않습니다.
U-Boot의 key-value blob과 달리 Barebox 환경은 파일과 script 중심이다. 저장 image의 CRC와 entry별 직접 파일 쓰기, 부팅 시 default overlay 순서를 확인한다.
이 파일의 helper는 host에서도 사용된다. 환경 적용을 항상 부트 CPU 실행으로 제한하지 않는다. CRC는 손상 검출이며 입력의 신뢰성이나 모든 경로·크기 검사를 대신하지 않는다.
RELATED SOURCE
함께 읽어야 하는 원본 코드
첫 코드 조각만으로 동작이 완성되지 않는 경우 호출 매크로, 객체 정의와 실제 실행 목록을 같은 페이지에 묶었다. 각 조각은 같은 기준 commit에서 가져왔다.
01. runtime environment를 envfs image로 직렬화
common/environment.c 295-397줄이다.
295/**
296 * Make the current environment persistent
297 * @param[in] filename where to store
298 * @param[in] dirname what to store (all files in this dir)
299 * @param[in] flags superblock flags (refer ENVFS_FLAGS_* macros)
300 * @return 0 on success, anything else in case of failure
301 *
302 * Note: This function will also be used on the host! See note in the header
303 * of this file.
304 */
305int envfs_save(const char *filename, const char *dirname, unsigned flags)
306{
307 struct envfs_super *super;
308 int envfd, size, ret;
309 struct action_data data = {};
310 void *buf = NULL, *wbuf;
311 struct envfs_entry *env;
312 __maybe_unused const char *defenv_path;
313
314 if (!filename)
315 return -ENOENT;
316
317 if (!dirname)
318 dirname = "/env";
319
320 data.writep = NULL;
321 data.base = dirname;
322
323#ifdef __BAREBOX__
324 defaultenv_load(TMPDIR, 0);
325#endif
326
327 if (flags & ENVFS_FLAGS_FORCE_BUILT_IN) {
328 size = 0; /* force no content */
329 } else {
330 /* first pass: calculate size */
331 recursive_action(dirname, ACTION_RECURSE | ACTION_SORT, file_action,
332 NULL, &data, 0);
333 recursive_action("/.defaultenv", ACTION_RECURSE | ACTION_SORT,
334 file_remove_action, NULL, &data, 0);
335 size = 0;
336
337 for (env = data.env; env; env = env->next) {
338 size += PAD4(env->size);
339 size += sizeof(struct envfs_inode);
340 size += PAD4(strlen(env->name) + 1);
341 size += sizeof(struct envfs_inode_end);
342 }
343 }
344
345 buf = xzalloc(size + sizeof(struct envfs_super));
346 data.writep = buf + sizeof(struct envfs_super);
347
348 super = buf;
349 super->magic = ENVFS_32(ENVFS_MAGIC);
350 super->major = ENVFS_MAJOR;
351 super->minor = ENVFS_MINOR;
352 super->size = ENVFS_32(size);
353 super->flags = ENVFS_32(flags);
354
355 if (!(flags & ENVFS_FLAGS_FORCE_BUILT_IN)) {
356 /* second pass: copy files to buffer */
357 env = data.env;
358 while (env) {
359 struct envfs_entry *next = env->next;
360
361 envfs_save_inode(&data, env);
362
363 free(env->buf);
364 free(env->name);
365 free(env);
366 env = next;
367 }
368 }
369
370 super->crc = ENVFS_32(crc32(0, buf + sizeof(struct envfs_super), size));
371 super->sb_crc = ENVFS_32(crc32(0, buf, sizeof(struct envfs_super) - 4));
372
373 envfd = open(filename, O_WRONLY | O_CREAT, S_IRUSR | S_IWUSR);
374 if (envfd < 0) {
375 printf("could not open %s: %m\n", filename);
376 ret = -errno;
377 goto out1;
378 }
379
380 ret = protect(envfd, ~0, 0, 0);
381
382 /* ENOSYS and EOPNOTSUPP aren't errors here, many devices don't need it */
383 if (ret && errno != ENOSYS && errno != EOPNOTSUPP) {
384 printf("could not unprotect %s: %m\n", filename);
385 goto out;
386 }
387
388 ret = erase(envfd, ERASE_SIZE_ALL, 0, ERASE_TO_WRITE);
389
390 /* ENOSYS and EOPNOTSUPP aren't errors here, many devices don't need it */
391 if (ret && errno != ENOSYS && errno != EOPNOTSUPP) {
392 printf("could not erase %s: %m\n", filename);
393 goto out;
394 }
395
396 size += sizeof(struct envfs_super);
397
DETAILS
CRC 검사와 파일 적용의 경계
파일을 바꾸기 전의 검사
envfs_load()는 허용 설정과 입력 경로를 확인하고 superblock magic·CRC를 검사한다. force-builtin이면 외부 data 처리를 건너뛰고 defaultenv_load()로 분기한다. 일반 경로는 data 전체를 읽어 CRC가 맞는지 확인한 뒤 entry 적용을 시작한다.
원자적 교체가 아닌 entry별 변경
envfs_load_data()는 이름을 목적 경로에 결합하고 각 파일을 O_TRUNC로 열거나 symlink를 변경한다. 뒤쪽 inode magic·open·write 오류로 중단돼도 앞선 파일을 되돌리는 rollback은 없다. ENV_FLAG_NO_OVERWRITE가 있고 기존 파일이 있으면 해당 entry는 건너뛴다.
반환값만으로 전부 성공했다고 판단하지 않는다
symlink 생성 오류는 로그를 남긴 뒤 순회를 계속하며 끝의 ret = 0에 의해 가려질 수 있다. 디렉터리 생성·close 결과도 모두 전파되지 않는다. short read/write 분기 일부는 -errno를 사용하므로 해당 반환값만으로 모든 entry의 적용 성공을 보증하지 않는다. 대상 파일과 로그를 함께 대조한다.
부팅 시 overlay 순서
load_environment()는 설정된 built-in default를 먼저 읽고 허용된 외부 envfs를 그 위에 적용한다. 이후 DT compatible overlay와 nvvar_load()가 이어진다. 외부 load의 반환값으로 이 initcall을 중단하지 않으므로 initcall의 0 반환은 외부 환경 적용 성공과 다르다.
IMPLEMENTATION NOTES
구현을 읽을 때 놓치기 쉬운 부분
envfs는 key-value blob이 아니라 파일 tree image다
superblock magic·CRC와 전체 data CRC를 검사한 뒤 inode entry를 순회해 대상 directory에 파일과 symlink를 직접 적용한다. 개별 inode magic, mode, file length와 image 범위를 확인해야 한다.
entry name이 concat_path_file(dir, name)으로 대상 경로가 되는 지점을 확인한다. 외부 image를 신뢰할 수 있는지는 이 경로 처리와 별도로 검토한다.
default environment와 persistent overlay 순서를 본다
부팅의 startup.c는 built-in default를 먼저 load하고, 설정이 허용하면 외부 envfs를 같은 /env에 load한다. CRC 오류는 적용 전 반환하지만 entry 처리 중 오류에는 이전 파일 변경을 되돌리는 rollback이 없다.
같은 파일의 source와 최종 내용을 표시해 우선순위를 검증한다.
saveenv의 atomicity는 backend에 달려 있다
saveenv의 storage image 기록과 loadenv의 runtime 파일 적용은 서로 다른 실패 경로다. 저장 매체의 전원 차단 위험은 별도로 시험하고, load 과정의 파일별 변경을 원자적 교체로 설명하지 않는다.
write 중 reset 뒤 어느 copy가 선택되는지 반복 시험한다.
OBJECT LIFETIME
객체와 수명
| 대상 | 만들어지는 시점 | 유효 범위 | 확인할 조건 |
|---|---|---|---|
envfs_super | envfs_load()의 stack | 함수 반환 전까지 | magic·header CRC·data size 확인 |
| envfs image data buffer | superblock 확인 뒤 할당·읽기 | 반환 경로에서 free | 전체 data CRC 확인 후 entry 적용 |
| built-in default 파일 | 부팅 초기화의 defaultenv_load() | /env 안에서 후속 변경까지 | 외부 envfs load보다 앞선 기본 layer |
| 외부 entry의 대상 파일 | envfs_load_data()의 각 open(O_TRUNC)·write | 파일이 다시 수정될 때까지 | 후반 오류에도 앞선 write rollback 없음 |
| symlink entry | envfs_load_data()의 unlink·symlink | 다음 변경까지 | 기존 경로를 바로 교체할 수 있음 |
FAILURE PATH
실패 지점과 증상
| # | 조건 | 관찰되는 증상 | 먼저 볼 단계 |
|---|---|---|---|
| 01 | superblock/data CRC 오류 | entry 적용 전 load 실패; 부팅 default 유지 | envfs_check_super/data |
| 02 | inode magic 오류 | load 중단; 앞선 파일 변경 가능 | envfs_load_data |
| 03 | 후반 entry 쓰기 오류 | 앞선 /env 파일만 바뀐 상태 가능 | envfs_load_data |
로그가 끊긴 함수뿐 아니라 그 함수에 주소, 크기, 플래그를 전달한 앞 단계도 조사한다. 오류 처리 후 등록된 객체나 하드웨어 설정이 그대로 남아 있는지도 확인한다.
EVIDENCE
반환값과 실제 파일을 대조한다
| 자료 | 확인할 차이 |
|---|---|
| 고정 버전의 environment.c·envfs-core.c | CRC 전 실패와 entry 적용 후 실패, NO_OVERWRITE 분기 |
| 보드 설정과 startup.c | built-in default·외부 autoload·DT overlay·nvvar 순서 |
| 격리 시험 directory의 전후 파일 목록·내용 | 앞서 바뀐 파일과 실패한 뒤쪽 entry를 구분 |
| 반환값과 symlink·write 오류 로그 | 로그만 남고 최종 0으로 끝나는 오류를 별도 확인 |
LAB
직접 확인할 실험
- 01saveenv/loadenv 전후 envfs header 비교
envfs superblock진입 전후에 envfs image의 주소·크기·반환값과 timestamp를 함께 남긴다. - 02CRC 오류 후 부팅 default 유지 확인
data CRC 검증진입 전후에 superblock/inodes의 주소·크기·반환값과 timestamp를 함께 남긴다. - 03후반 entry 오류 때 앞선 파일 상태 확인
envfs_load_data()진입 전후에 runtime directory의 주소·크기·반환값과 timestamp를 함께 남긴다.
PRIMARY REFERENCES