U-Boot · source analysis

Environment import와 영속 저장

CRC가 붙은 저장 매체의 environment를 hash table로 가져오고 default 환경으로 fallback하는 경로를 읽습니다.

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

Series
14 / 22
Baseline
v2026.07
Commit
ece349ade297
Source
env/common.c:419-507 (발췌 범위)

저장된 값이 곧 실행 중 값은 아니다

이 글은 U-Boot v2026.07의 env_import()를 중심으로 persistent environment의 CRC 확인, RAM 해시 테이블 공개, 기본값 복구를 구분한다. 사용 가능한 저장 backend와 중복 copy 정책은 보드 구성에 따라 다르다.

env set은 메모리 안의 변수를 바꾸고, env save를 성공적으로 수행해야 그 변경을 다음 부팅에도 읽을 수 있다. CRC는 저장 데이터의 오류 검출이며 출처 인증이 아니다. 부팅 중 GD_FLG_ENV_READY 전후로 env_get()의 조회 경로도 달라진다.

storage blob과 RAM 해시 테이블

그림 1. CRC·import·기본값 복구는 조건부 경로
저장 환경의 CRC와 선택적 중복 copy를 확인해 RAM hash table로 가져오는 경로. CRC 또는 import 실패는 built-in default를 RAM에 넣으려 시도하며, env save는 별도 단계임

위쪽 중복 copy 선택은 CONFIG_ENV_REDUNDANT인 경우에만 있다. env_import()의 check가 0이면 이 함수 안에서 CRC를 다시 검사하지 않는다. 좁은 화면에서는 그림을 좌우로 스크롤한다. 원본 env_import() · 중복 copy 경로

성공·실패·저장은 세 흐름

입력 / 사건결정 함수RAM에 남는 상태호출자가 확인할 것
backend가 blob을 읽음env_load()선택된 backend의 데이터가 import 후보priority, init 여부, load 반환값
CRC 검사 통과env_import(check=1)himport_r 성공 시 env_htab과 GD_FLG_ENV_READY이어지는 fdt_addr 갱신의 반환값도 별도
CRC 불일치env_set_default("bad CRC")built-in default를 RAM에 import하려 시도-ENOMSG; env_load가 다른 backend도 시도할 수 있음
해시 import 실패env_set_default("import failed")default import를 다시 시도-EIO; 실패 전 일부 상태를 성공으로 오인하지 않기
사용자 변경 후 저장env set → env saveset은 RAM만 변경save backend 반환값과 다음 reset 뒤 실제 값

위 표의 env_load()는 우선순위별 backend를 시도하고, 성공한 backend의 priority를 gd->env_load_prio에 기록한다. env_import()의 반환값만으로 READY 플래그의 참·거짓을 역추론하지 않는다.

환경 상태와 소유자의 이동

상태저장 위치 / 소유자검사 또는 변환다음에 읽는 쪽
default environment빌드된 이미지의 default_environmentpersistent가 없거나 실패할 때 env_set_default()RAM env_htab
persistent blob보드별 env backendenv_t의 CRC32는 data[ENV_SIZE] 검사. 중복 구성의 flags 판정은 별도env_import() 또는 env_import_redund()
runtime hash tableRAM env_htabhimport_r() 성공 후 GD_FLG_ENV_READYenv_get()와 boot 정책
RAM 수정env set/env_set()현재 해시 테이블만 수정현재 부팅의 변수 조회
다음 부팅용 저장env save backend내보내기·CRC 계산과 매체 write는 backend 경로다음 부팅의 backend load

원본 코드

아래 코드는 U-Boot v2026.07의 env/common.c에서 419-507줄을 그대로 가져온 것이다.

commitece349ade2973e220f524ce59e59711cc919263fanchor · L443int env_import(const char *buf
419int env_set_default_vars(int nvars, char * const vars[], int flags)
420{
421	/*
422	 * Special use-case: import from default environment
423	 * (and use \0 as a separator)
424	 */
425
426	/*
427	 * When vars are passed remove variables that are not in
428	 * the default environment.
429	 */
430	if (!nvars)
431		flags |= H_NOCLEAR;
432
433	flags |= H_DEFAULT;
434	return himport_r(&env_htab, default_environment,
435				sizeof(default_environment), '\0',
436				flags, 0, nvars, vars);
437}
438
439/*
440 * Check if CRC is valid and (if yes) import the environment.
441 * Note that "buf" may or may not be aligned.
442 */
443int env_import(const char *buf, int check, int flags)
444{
445	env_t *ep = (env_t *)buf;
446
447	if (check) {
448		uint32_t crc;
449
450		memcpy(&crc, &ep->crc, sizeof(crc));
451
452		if (crc32(0, ep->data, ENV_SIZE) != crc) {
453			env_set_default("bad CRC", 0);
454			return -ENOMSG; /* needed for env_load() */
455		}
456	}
457
458	if (himport_r(&env_htab, (char *)ep->data, ENV_SIZE, '\0', flags, 0,
459			0, NULL)) {
460		gd->flags |= GD_FLG_ENV_READY;
461
462		/* This has to be done after GD_FLG_ENV_READY is set */
463		return env_update_fdt_addr_from_bloblist();
464	}
465
466	pr_err("Cannot import environment: errno = %d\n", errno);
467
468	env_set_default("import failed", 0);
469
470	return -EIO;
471}
472
473#ifdef CONFIG_ENV_REDUNDANT
474static unsigned char env_flags;
475
476#define ENV_SINGLE_HEADER_SIZE	(sizeof(uint32_t))
477#define ENV_SINGLE_SIZE		(CONFIG_ENV_SIZE - ENV_SINGLE_HEADER_SIZE)
478
479typedef struct {
480	uint32_t	crc;			/* CRC32 over data bytes */
481	unsigned char	data[ENV_SINGLE_SIZE];	/* Environment data */
482} env_single_t;
483
484int env_check_redund(const char *buf1, int buf1_read_fail,
485		     const char *buf2, int buf2_read_fail)
486{
487	int crc1_ok = 0, crc2_ok = 0, i;
488	env_t *tmp_env1, *tmp_env2;
489	env_single_t *tmp_envs;
490
491	tmp_env1 = (env_t *)buf1;
492	tmp_env2 = (env_t *)buf2;
493	tmp_envs = (env_single_t *)buf1;
494
495	if (buf1_read_fail && buf2_read_fail) {
496		puts("*** Error - No Valid Environment Area found\n");
497		return -EIO;
498	} else if (buf1_read_fail || buf2_read_fail) {
499		puts("*** Warning - some problems detected ");
500		puts("reading environment; recovered successfully\n");
501	}
502
503	if (!buf1_read_fail)
504		crc1_ok = crc32(0, tmp_env1->data, ENV_SIZE) ==
505				tmp_env1->crc;
506	if (!buf2_read_fail)
507		crc2_ok = crc32(0, tmp_env2->data, ENV_SIZE) ==

발췌 범위와 반환 경계

아래 원본 발췌 89행은 고정 커밋 ece349ade2973e220f524ce59e59711cc919263f의 env/common.c 419–507행과 행별로 대조했다. 앞부분 419–437행은 기본 변수 복원 함수이고, env_import() 본문은 443행부터다. 코드와 원래 행번호는 수정하지 않았다.

  • 447–456행: check가 참일 때에만 CRC를 검사한다. CRC 불일치에서 default import를 시도한 뒤 -ENOMSG를 반환한다.
  • 458–470행: himport_r()가 성공하면 READY를 먼저 세우고 fdt_addr 갱신 결과를 반환한다. parser 실패는 default 경로와 -EIO다.
  • 484행 이후: 중복 copy는 각 CRC와 flags를 판정한 뒤 선택한다. 이 설정이 없으면 단일 blob을 읽는 경로다.

부팅 시 조회 방법이 바뀌는 순간

GD_FLG_ENV_READY가 없으면 env_get()는 제한된 초기 경로 env_get_f()로 선형 환경에서 값을 복사한다. READY 뒤에는 env_htab에서 찾는다. “환경 변수가 있다”는 말만으로 두 단계의 주소·수명·허용 동작이 같다고 볼 수 없다.

고정 원본의 env_import()는 CRC 불일치 때 env_set_default()를 호출하고 -ENOMSG를 돌려준다. 이 에러는 상위 env_load()가 다른 backend를 시도하는 데 쓰일 수 있다. 결과적으로 한 시점의 default import와 최종 선택된 backend를 구분해 로그를 읽어야 한다.

성공 branch에서는 GD_FLG_ENV_READY를 세운 다음 env_update_fdt_addr_from_bloblist()의 반환값을 그대로 반환한다. 따라서 env_import() != 0이라는 관측만으로 해시 테이블이 준비되지 않았다고 단정하면 안 된다.

단일 copy와 중복 copy의 조건

구성 / 판정실제 의미오해하기 쉬운 결론
단일 env_tCRC32 필드와 data. ENV_SIZE = CONFIG_ENV_SIZE - headerCRC가 boot script의 출처까지 인증하지는 않는다.
CONFIG_ENV_REDUNDANT두 copy의 read 성공·CRC와 flags serial을 비교한다.항상 물리적으로 첫 copy가 최신이라는 뜻이 아니다.
한쪽 CRC만 유효유효한 copy를 고른다.선택 후 env_import(check=0)가 CRC를 또 검사하지는 않는다.
둘 다 유효flags 비교와 255→0 wrap 예외로 선택한다.단순 큰 숫자 우선 규칙만은 아니다.
둘 다 CRC 실패선택 실패. 설정 시 ENV_REDUNDANT_UPGRADE로 예전 단일 형식의 1차 copy를 재검사할 수 있다.업그레이드 경로는 모든 보드에서 항상 켜져 있지 않다.

중복 판정 원문과 env_t/ENV_SIZE 정의를 설정별로 읽는다. 저장의 전원 차단 내구성은 이 함수만으로 보장되지 않으며 backend의 write 순서를 별도로 확인해야 한다.

객체의 유효 범위

객체누가 만든 값인가언제 신뢰할 수 있는가
env_t 입력 buffer환경 저장 backendread 성공 및 설정에 맞는 CRC/형식 판정 뒤. 포인터가 정렬돼 있다고 가정하지 않는다.
default_environment빌드된 U-Boot 이미지persistent 실패 시 RAM table을 복구할 원천. 저장된 사용자 설정 자체는 아니다.
env_htabhimport_r()READY 뒤의 runtime 조회 대상. env set은 이 RAM 상태를 바꾼다.
gd->env_load_prioenv_load()성공 backend 또는 fallback을 위한 저장 대상 선택에 사용된다.

실패와 복구의 구체적 경계

증상원본에서 볼 반환다음 확인
저장 환경 CRC가 틀림env_import()의 -ENOMSG; default import 시도backend 주소·크기·CONFIG_ENV_SIZE, 이어지는 다른 backend load 여부
CRC는 맞는데 변수 가져오기 실패himport_r() 실패 후 -EIO문자열 형식·플래그·errno, default import 성공 여부
import 뒤에도 호출자가 실패를 받음fdt_addr 갱신 반환값READY 플래그와 bloblist/FDT 조건을 각각 기록
save 뒤 reset에서 값이 사라짐backend의 save() 결과실제 선택 backend와 매체 write·readback; RAM의 env set만 했는지

보드에서 수집할 증거

관측기록할 값구분하는 질문
env info -p 및 설정backend 종류, offset/장치, CONFIG_ENV_SIZE, redundant 여부어느 persistent 위치를 읽고 저장하는가?
load 로그와 상태backend 우선순위, 각 load 반환값, gd->env_load_priodefault import가 최종 상태인가, 다음 backend가 성공했는가?
raw blob 판정read 성공, data CRC, redundant flagsCRC 실패와 copy 선택을 혼동했는가?
runtime 조회READY 전후 값, env print, 재부팅 후 값RAM 변경과 저장소 반영을 구분했는가?

재현 가능한 네 단계 실험

  1. 01
    읽는 위치를 확정

    env info -p와 빌드 설정에서 backend와 크기를 확인하고 원본 blob을 별도로 보관한다.

  2. 02
    CRC 오류를 별도 복제본에서 재현

    데이터 한 바이트를 바꿨을 때 -ENOMSG, default import, 후속 backend 시도를 각각 기록한다. 실제 장비의 유일한 복구 copy는 손대지 않는다.

  3. 03
    RAM과 저장소를 비교

    env set 뒤와 env save 뒤의 값을 따로 읽고, 재부팅해서 persistent 반영을 확인한다.

  4. 04
    redundant 구성에서만 두 copy 비교

    두 copy의 CRC·flags와 실제 선택 결과를 대조한다. 전원 차단 시험은 backend의 안전한 검증 환경에서만 수행한다.

원문과 다음 글