U-Boot · source analysis

Fastboot USB function과 command dispatch

USB 가젯 구성에 fastboot 기능을 등록하고 download·flash 명령을 처리하는 과정을 살펴봅니다.

이 글은 U-Boot v2026.07의 고정 소스와 구성 옵션을 기준으로 읽습니다. 실제 제품의 Fastboot 기능과 저장 백엔드는 빌드 설정 및 보드 구성에 따라 달라집니다.

Series
18 / 22
Baseline
v2026.07
Commit
ece349ade297
Source
drivers/usb/gadget/f_fastboot.c:344-432 (발췌 범위)

USB 등록, 다운로드, flash는 어디서 갈라지는가?

이 글의 89행 발췌는 fastboot_set_alt()의 끝과 fastboot_add() 및 bulk IN 전송의 시작을 보여 준다. USB 기능 등록과 endpoint 활성화는 여기서 보이지만, 명령 해석과 저장 장치 쓰기는 다른 함수·파일에 있다.

download 명령은 RAM 버퍼로 데이터를 받으며 자동으로 flash하지 않는다. 나중에 별도 flash:<partition> 명령이 들어오고 해당 백엔드가 활성화된 경우에만 저장 작업으로 간다. 아래 그림은 이 조건을 분리한다.

등록 객체와 데이터 버퍼의 소유 경계

그림 1. gadget 기능 · USB 요청 · 다운로드/저장 객체는 서로 다른 층에 있다

등록 자체가 다운로드나 flash 완료를 뜻하지 않는다. OUT request가 재큐되면서 이후 명령도 같은 transport를 사용한다.

OUT 완료 뒤 갈라지는 세 경로

그림 2. 명령, 다운로드 데이터, 저장 쓰기의 조건부 관계
bulk OUT completionrx_handler_command() → 길이 검사 → fastboot_handle_command()설정 완료 뒤 큐에 있던 OUT 요청이 끝났을 때 시작
download 명령RAM 수신 경로

크기 검사를 통과하면 DATA. OUT 완료 함수를 rx_handler_dl_image()로 바꾸고 수신 조각을 fastboot_data_download()로 복사한다.

전량 수신 → fastboot_data_complete() → image_size 설정 + OKAY

별도 flash 명령저장 백엔드 경로

CONFIG_FASTBOOT_FLASH로 명령이 활성화된 경우 flash()가 다운로드 주소·image_size를 선택된 block/MMC/NAND/SPI 백엔드에 전달한다.

백엔드 결과가 OKAY/FAIL 응답을 작성

getvar 조회정보 응답 경로

조회 handler가 응답을 만든다. boot/reboot, erase, OEM 명령은 서로 다른 경로이며 이 조회 상자에 포함하지 않는다. 미지원 명령은 FAIL.

flash 경로로 자동 합류하지 않음

fastboot_tx_write_str() → bulk IN request응답 문자열을 큐에 넣는다. 큐 등록 성공과 호스트 수신 완료는 서로 다른 시점이다.
download의 OKAY는 RAM 수신 완료이며 flash 성공 신호가 아니다. flash는 이후 호스트가 별도 명령을 보낼 때만 실행한다.

콜백마다 바뀌는 상태와 다음 소비자

행은 하나의 필수 호출열이 아니다. 등록·설정은 먼저 일어나고, 명령 종류에 따라 아래 수신 경로 중 하나를 선택한다.

경계조건 / 담당 소스성공 뒤 상태실패 또는 다음 동작
기능 등록fastboot_add() → usb_add_function(); f_fastboot.cusb_function callback 등록, bind에서 interface/endpoint descriptor 배정추가 실패 시 할당한 f_fastboot 해제
인터페이스 활성화fastboot_set_alt(); f_fastboot.cIN/OUT enable 및 request 생성, OUT request 큐 등록오류 시 fastboot_disable() 경유; 아직 명령 처리 전
명령 OUT 완료rx_handler_command() → fastboot_handle_command(); USB/공통 코드길이 검사 후 명령별 응답 작성미지원/넘침은 FAIL; DATA일 때만 다운로드 콜백으로 전환
데이터 OUT 완료rx_handler_dl_image() → fastboot_data_download()수신 조각을 RAM에 복사; 완료 시 image_size 확정완료 응답 뒤 명령 콜백으로 복귀; storage write 없음
flash 명령flash() in fb_command.c; 구성된 백엔드만대상 partition에 쓰고 응답 문자열 준비백엔드 오류는 FAIL; IN 전송으로 호스트에 통지

원본 코드

아래 코드는 U-Boot v2026.07의 drivers/usb/gadget/f_fastboot.c에서 344-432줄을 그대로 가져온 것이다.

commitece349ade2973e220f524ce59e59711cc919263fanchor · L368static int fastboot_add(struct usb_configuration *c)
344	ret = usb_ep_enable(f_fb->in_ep, d);
345	if (ret) {
346		puts("failed to enable in ep\n");
347		goto err;
348	}
349
350	f_fb->in_req = fastboot_start_ep(f_fb->in_ep);
351	if (!f_fb->in_req) {
352		puts("failed alloc req in\n");
353		ret = -EINVAL;
354		goto err;
355	}
356	f_fb->in_req->complete = fastboot_complete;
357
358	ret = usb_ep_queue(f_fb->out_ep, f_fb->out_req, 0);
359	if (ret)
360		goto err;
361
362	return 0;
363err:
364	fastboot_disable(f);
365	return ret;
366}
367
368static int fastboot_add(struct usb_configuration *c)
369{
370	struct f_fastboot *f_fb = fastboot_func;
371	int status;
372
373	debug("%s: cdev: 0x%p\n", __func__, c->cdev);
374
375	if (!f_fb) {
376		f_fb = memalign(CONFIG_SYS_CACHELINE_SIZE, sizeof(*f_fb));
377		if (!f_fb)
378			return -ENOMEM;
379
380		fastboot_func = f_fb;
381		memset(f_fb, 0, sizeof(*f_fb));
382	}
383
384	f_fb->usb_function.name = "f_fastboot";
385	f_fb->usb_function.bind = fastboot_bind;
386	f_fb->usb_function.unbind = fastboot_unbind;
387	f_fb->usb_function.set_alt = fastboot_set_alt;
388	f_fb->usb_function.disable = fastboot_disable;
389	f_fb->usb_function.strings = fastboot_strings;
390
391	status = usb_add_function(c, &f_fb->usb_function);
392	if (status) {
393		free(f_fb);
394		fastboot_func = NULL;
395	}
396
397	return status;
398}
399DECLARE_GADGET_BIND_CALLBACK(usb_dnl_fastboot, fastboot_add);
400
401static int fastboot_tx_write(const char *buffer, unsigned int buffer_size)
402{
403	struct usb_request *in_req = fastboot_func->in_req;
404	int ret;
405
406	memcpy(in_req->buf, buffer, buffer_size);
407	in_req->length = buffer_size;
408
409	usb_ep_dequeue(fastboot_func->in_ep, in_req);
410
411	ret = usb_ep_queue(fastboot_func->in_ep, in_req, 0);
412	if (ret)
413		printf("Error %d on queue\n", ret);
414	return 0;
415}
416
417static int fastboot_tx_write_str(const char *buffer)
418{
419	return fastboot_tx_write(buffer, strlen(buffer));
420}
421
422static void compl_do_reset(struct usb_ep *ep, struct usb_request *req)
423{
424	g_dnl_unregister();
425	do_reset(NULL, 0, 0, NULL);
426}
427
428static unsigned int rx_bytes_expected(struct usb_ep *ep)
429{
430	int rx_remain = fastboot_data_remaining();
431	unsigned int rem;
432	unsigned int maxpacket = usb_endpoint_maxp(ep->desc);

발췌 범위와 읽기 기준

고정 commit의 f_fastboot.c:344–432는 fastboot_set_alt() 끝(L344–366), fastboot_add()(L368–398), bind callback 선언(L399)과 IN 전송 함수 시작을 포함한다. 이 89행은 명령 parser나 flash backend의 구현이 아니다.

명령·다운로드 분기는 같은 파일의 rx_handler_command()와 rx_handler_dl_image(), 명령 표와 다운로드 버퍼 상태는 drivers/fastboot/fb_command.c, 실제 저장 쓰기는 빌드가 선택한 백엔드에서 확인한다.

코드 순서대로 읽는 다섯 경계

01

등록과 bind

g_dnl_do_config()가 이름이 맞는 bind callback을 선택한다. fastboot_add()는 struct f_fastboot를 준비하고 callback을 채워 usb_add_function()에 넘긴다. fastboot_bind()가 interface 번호와 endpoint를 선택하며, 아직 bulk 데이터는 수신하지 않았다.

02

set_alt와 request 수명

fastboot_set_alt()는 속도별 descriptor로 OUT/IN endpoint를 활성화하고 각각 4 KiB request buffer를 만든다. OUT 완료 함수를 명령 수신으로 설정한 뒤 usb_ep_queue()한다. 최초 OUT enable 실패는 바로 반환하고, 이후 할당·enable·queue 실패는 fastboot_disable()를 거쳐 생성된 request를 해제한다.

03

명령을 수신했을 때

rx_handler_command()는 정상 완료와 길이를 검사한 다음 fastboot_handle_command()의 명령 표로 분기한다. DATA 응답에만 OUT 완료 함수를 데이터 수신으로 교체한다. 그 밖의 명령은 각 handler의 결과를 응답 문자열로 보낸다.

04

download는 RAM으로 끝난다

공통 코드의 download()는 요청 크기를 fastboot_buf_size와 비교한다. 데이터 수신 콜백은 남은 바이트만 복사하고, 전량 수신 시 image_size와 filesize를 확정한 뒤 명령 수신으로 돌아간다. 이때 저장 매체 쓰기는 수행하지 않는다.

05

flash는 별도 명령과 백엔드

flash:<partition>이 들어와 CONFIG_FASTBOOT_FLASH가 허용할 때만 공통 flash()가 활성화된 백엔드를 호출한다. MMC의 일반 파티션 경로는 partition 조회 후 sparse/raw 쓰기를 고른다. 응답 내용은 백엔드 결과에서 만들고 USB IN으로 전송한다.

그림 밖의 명령도 구분한다. 위 세 갈래는 명령 전체 목록이 아니다. erase와 설정별 OEM 명령에도 저장장치 변경 경로가 있으며, boot/reboot는 별도 완료 callback에서 실행된다. flash()의 백엔드 조건은 독립된 if들이므로 이 함수만으로 단일 백엔드 선택을 보장하지 않는다.

새 download()는 수신 카운터를 초기화하지만 기존 image_size를 지우지는 않는다. 전량 수신한 fastboot_data_complete()가 크기를 갱신한다. 중단된 다운로드가 RAM이나 이전 크기를 원복했다고 보지 않으며, 공통 flash()만으로 새 이미지의 완결성 검증을 보장하지 않는다.

OUT 완료의 status 오류는 재큐 전에 바로 반환한다. 정상 끝부분의 usb_ep_queue() 반환값도 검사하지 않는다. IN 큐 등록 실패·OUT 재큐 실패·저장 결과·호스트의 실제 수신은 각각 다른 증거로 확인해야 한다. 이 검토에서는 USB 명령, 다운로드, flash 또는 erase를 실제 장치에 실행하지 않았다.

비동기 USB와 저장 결과를 구분하기

01

응답 생성과 실제 IN 전송은 다르다

명령 handler는 OKAY/FAIL/DATA 문자열을 만들고 fastboot_tx_write_str()가 IN request를 큐에 넣는다. 고정 소스의 fastboot_tx_write()는 큐 실패를 출력하지만 반환값은 0이므로, 호출자의 반환값만으로 호스트 수신을 증명할 수 없다.

02

같은 OUT request, 다른 완료 함수

DATA 뒤에는 OUT request의 complete가 rx_handler_dl_image()로 바뀐다. 남은 바이트가 0이 되면 다시 rx_handler_command()로 되돌린다. 명령과 데이터 조각을 같은 parser 입력으로 혼동하면 안 된다.

03

flash 지원은 빌드와 대상에 따라 다르다

CONFIG_FASTBOOT_FLASH가 꺼지면 명령 표의 dispatch는 비어 미지원 응답을 만든다. 활성 상태에서도 block/MMC/NAND/SPI의 실제 쓰기 및 파티션 검사는 해당 백엔드에 있다. 이 글의 89행 USB 발췌만으로 저장 작업의 성공을 판정할 수 없다.

객체와 수명

객체만들어지는 곳쓰는 곳 / 끝
fastboot_func / struct f_fastbootfastboot_add()에서 최초 할당function callback과 endpoint/request 포인터; usb_add_function() 실패 시 해제
bulk IN/OUT endpoint와 requestfastboot_bind()에서 endpoint 선택, set_alt()에서 enable/request 할당OUT command/data 수신과 IN 응답 전송; fastboot_disable()에서 request 해제·endpoint 비활성화
fastboot_buf_addr, image_size공통 Fastboot 초기화·download 완료download 데이터의 RAM 보관; 후속 flash/boot 명령이 사용할 수 있음
partition 및 저장 장치 상태선택된 flash 백엔드별도 flash 명령에서만 변경

실패 지점과 관찰 결과

조건고정 소스의 분기관찰 기준
endpoint/request 준비 실패OUT enable 실패는 즉시 반환; 이후 실패는 set_alt()의 err: → fastboot_disable()명령 OUT request가 등록되지 않음
명령 패킷이 버퍼를 채움req->actual >= req->length이면 FAIL(buffer overflow)명령 parser 호출 전 차단
download 크기 초과download()의 fastboot_buf_size 검사 → FAILDATA를 보내지 않아 데이터 수신 상태로 전환하지 않음
미지원 flash 명령·백엔드 오류명령 표 dispatch 없음 또는 백엔드가 FAIL 작성USB 응답과 실제 저장 결과를 함께 확인

소스·빌드·호스트에서 확인할 증거

대상읽기 전용 확인 방법판정할 내용
고정 소스rg -n 'fastboot_add|fastboot_set_alt|rx_handler_command' drivers/usb/gadget/f_fastboot.c등록과 수신 callback의 함수 경계
명령·백엔드 설정rg 'CONFIG_FASTBOOT_FLASH|CONFIG_FASTBOOT_BUF' .configflash dispatch/버퍼가 해당 보드에 포함됐는지
빌드 심볼${CROSS_COMPILE}nm -n u-boot | grep 'fastboot_add'심볼이 남은 빌드에서 함수 이름 확인. 최적화·strip 시 없을 수 있음
USB 연결fastboot devices호스트가 Fastboot 인터페이스를 인식하는지
명령 응답fastboot getvar allIN 응답 수신 여부. 저장 쓰기 완료 증거는 아님

경계를 직접 확인하는 실험

  1. 01
    연결과 명령 응답

    대상에서 Fastboot USB 기능을 활성화한 뒤 호스트의 fastboot devices와 fastboot getvar all로 enumeration, 명령 OUT, 응답 IN을 확인한다.

  2. 02
    download 한계와 RAM 상태

    시험 환경에서 허용 크기의 작은 데이터를 download해 DATA 다음 OKAY를 확인한다. 크기 초과 요청은 FAIL이고 data callback으로 전환되지 않아야 한다.

  3. 03
    flash는 별도 검증

    쓰기 가능한 시험 대상에서만 별도 flash:<partition> 명령을 실행한다. 선택된 백엔드 로그와 파티션 내용으로 결과를 검증하고, 앞 단계 download 성공과 구분한다.

원문과 다음 글