QUESTION
USB 등록, 다운로드, flash는 어디서 갈라지는가?
이 글의 89행 발췌는 fastboot_set_alt()의 끝과 fastboot_add() 및 bulk IN 전송의 시작을 보여 준다. USB 기능 등록과 endpoint 활성화는 여기서 보이지만, 명령 해석과 저장 장치 쓰기는 다른 함수·파일에 있다.
download 명령은 RAM 버퍼로 데이터를 받으며 자동으로 flash하지 않는다. 나중에 별도 flash:<partition> 명령이 들어오고 해당 백엔드가 활성화된 경우에만 저장 작업으로 간다. 아래 그림은 이 조건을 분리한다.
STRUCTURE
등록 객체와 데이터 버퍼의 소유 경계
g_dnl_do_config()선택된 bind callback → fastboot_add() → usb_add_function(); fastboot_bind()가 interface ID와 bulk endpoint descriptor를 배정한다.
fastboot_set_alt()속도에 맞는 IN/OUT endpoint 활성화, 두 request/buffer 생성, OUT request 큐 등록. fastboot_disable()는 이 request를 해제한다.
rx_handler_command() 또는 rx_handler_dl_image()가 처리한다. 응답은 bulk IN, flash 쓰기는 선택된 저장 백엔드에서 수행된다.
struct f_fastbootUSB function, IN/OUT endpoint와 request 포인터. 발췌의 fastboot_func가 가리킨다.fastboot_buf_addr + image_sizeFastboot 공통 코드의 다운로드 주소와 완성된 이미지 크기. USB request의 4 KiB 버퍼와 구별한다.등록 자체가 다운로드나 flash 완료를 뜻하지 않는다. OUT request가 재큐되면서 이후 명령도 같은 transport를 사용한다.
CALL PATH
OUT 완료 뒤 갈라지는 세 경로
rx_handler_command() → 길이 검사 → fastboot_handle_command()설정 완료 뒤 큐에 있던 OUT 요청이 끝났을 때 시작크기 검사를 통과하면 DATA. OUT 완료 함수를 rx_handler_dl_image()로 바꾸고 수신 조각을 fastboot_data_download()로 복사한다.
전량 수신 → fastboot_data_complete() → image_size 설정 + OKAY
CONFIG_FASTBOOT_FLASH로 명령이 활성화된 경우 flash()가 다운로드 주소·image_size를 선택된 block/MMC/NAND/SPI 백엔드에 전달한다.
백엔드 결과가 OKAY/FAIL 응답을 작성
조회 handler가 응답을 만든다. boot/reboot, erase, OEM 명령은 서로 다른 경로이며 이 조회 상자에 포함하지 않는다. 미지원 명령은 FAIL.
flash 경로로 자동 합류하지 않음
fastboot_tx_write_str() → bulk IN request응답 문자열을 큐에 넣는다. 큐 등록 성공과 호스트 수신 완료는 서로 다른 시점이다.OKAY는 RAM 수신 완료이며 flash 성공 신호가 아니다. flash는 이후 호스트가 별도 명령을 보낼 때만 실행한다.STATE LEDGER
콜백마다 바뀌는 상태와 다음 소비자
행은 하나의 필수 호출열이 아니다. 등록·설정은 먼저 일어나고, 명령 종류에 따라 아래 수신 경로 중 하나를 선택한다.
| 경계 | 조건 / 담당 소스 | 성공 뒤 상태 | 실패 또는 다음 동작 |
|---|---|---|---|
| 기능 등록 | fastboot_add() → usb_add_function(); f_fastboot.c | usb_function callback 등록, bind에서 interface/endpoint descriptor 배정 | 추가 실패 시 할당한 f_fastboot 해제 |
| 인터페이스 활성화 | fastboot_set_alt(); f_fastboot.c | IN/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 전송으로 호스트에 통지 |
UPSTREAM SOURCE
원본 코드
아래 코드는 U-Boot v2026.07의 drivers/usb/gadget/f_fastboot.c에서 344-432줄을 그대로 가져온 것이다.
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);
READING CONTRACT
발췌 범위와 읽기 기준
고정 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, 실제 저장 쓰기는 빌드가 선택한 백엔드에서 확인한다.
DETAILS
코드 순서대로 읽는 다섯 경계
등록과 bind
g_dnl_do_config()가 이름이 맞는 bind callback을 선택한다. fastboot_add()는 struct f_fastboot를 준비하고 callback을 채워 usb_add_function()에 넘긴다. fastboot_bind()가 interface 번호와 endpoint를 선택하며, 아직 bulk 데이터는 수신하지 않았다.
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를 해제한다.
명령을 수신했을 때
rx_handler_command()는 정상 완료와 길이를 검사한 다음 fastboot_handle_command()의 명령 표로 분기한다. DATA 응답에만 OUT 완료 함수를 데이터 수신으로 교체한다. 그 밖의 명령은 각 handler의 결과를 응답 문자열로 보낸다.
download는 RAM으로 끝난다
공통 코드의 download()는 요청 크기를 fastboot_buf_size와 비교한다. 데이터 수신 콜백은 남은 바이트만 복사하고, 전량 수신 시 image_size와 filesize를 확정한 뒤 명령 수신으로 돌아간다. 이때 저장 매체 쓰기는 수행하지 않는다.
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를 실제 장치에 실행하지 않았다.
IMPLEMENTATION NOTES
비동기 USB와 저장 결과를 구분하기
응답 생성과 실제 IN 전송은 다르다
명령 handler는 OKAY/FAIL/DATA 문자열을 만들고 fastboot_tx_write_str()가 IN request를 큐에 넣는다. 고정 소스의 fastboot_tx_write()는 큐 실패를 출력하지만 반환값은 0이므로, 호출자의 반환값만으로 호스트 수신을 증명할 수 없다.
같은 OUT request, 다른 완료 함수
DATA 뒤에는 OUT request의 complete가 rx_handler_dl_image()로 바뀐다. 남은 바이트가 0이 되면 다시 rx_handler_command()로 되돌린다. 명령과 데이터 조각을 같은 parser 입력으로 혼동하면 안 된다.
flash 지원은 빌드와 대상에 따라 다르다
CONFIG_FASTBOOT_FLASH가 꺼지면 명령 표의 dispatch는 비어 미지원 응답을 만든다. 활성 상태에서도 block/MMC/NAND/SPI의 실제 쓰기 및 파티션 검사는 해당 백엔드에 있다. 이 글의 89행 USB 발췌만으로 저장 작업의 성공을 판정할 수 없다.
OBJECT LIFETIME
객체와 수명
| 객체 | 만들어지는 곳 | 쓰는 곳 / 끝 |
|---|---|---|
fastboot_func / struct f_fastboot | fastboot_add()에서 최초 할당 | function callback과 endpoint/request 포인터; usb_add_function() 실패 시 해제 |
| bulk IN/OUT endpoint와 request | fastboot_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 명령에서만 변경 |
FAILURE PATH
실패 지점과 관찰 결과
| 조건 | 고정 소스의 분기 | 관찰 기준 |
|---|---|---|
| endpoint/request 준비 실패 | OUT enable 실패는 즉시 반환; 이후 실패는 set_alt()의 err: → fastboot_disable() | 명령 OUT request가 등록되지 않음 |
| 명령 패킷이 버퍼를 채움 | req->actual >= req->length이면 FAIL(buffer overflow) | 명령 parser 호출 전 차단 |
| download 크기 초과 | download()의 fastboot_buf_size 검사 → FAIL | DATA를 보내지 않아 데이터 수신 상태로 전환하지 않음 |
| 미지원 flash 명령·백엔드 오류 | 명령 표 dispatch 없음 또는 백엔드가 FAIL 작성 | USB 응답과 실제 저장 결과를 함께 확인 |
EVIDENCE
소스·빌드·호스트에서 확인할 증거
| 대상 | 읽기 전용 확인 방법 | 판정할 내용 |
|---|---|---|
| 고정 소스 | rg -n 'fastboot_add|fastboot_set_alt|rx_handler_command' drivers/usb/gadget/f_fastboot.c | 등록과 수신 callback의 함수 경계 |
| 명령·백엔드 설정 | rg 'CONFIG_FASTBOOT_FLASH|CONFIG_FASTBOOT_BUF' .config | flash dispatch/버퍼가 해당 보드에 포함됐는지 |
| 빌드 심볼 | ${CROSS_COMPILE}nm -n u-boot | grep 'fastboot_add' | 심볼이 남은 빌드에서 함수 이름 확인. 최적화·strip 시 없을 수 있음 |
| USB 연결 | fastboot devices | 호스트가 Fastboot 인터페이스를 인식하는지 |
| 명령 응답 | fastboot getvar all | IN 응답 수신 여부. 저장 쓰기 완료 증거는 아님 |
LAB
경계를 직접 확인하는 실험
- 01연결과 명령 응답
대상에서 Fastboot USB 기능을 활성화한 뒤 호스트의
fastboot devices와fastboot getvar all로 enumeration, 명령 OUT, 응답 IN을 확인한다. - 02download 한계와 RAM 상태
시험 환경에서 허용 크기의 작은 데이터를 download해
DATA다음OKAY를 확인한다. 크기 초과 요청은FAIL이고 data callback으로 전환되지 않아야 한다. - 03flash는 별도 검증
쓰기 가능한 시험 대상에서만 별도
flash:<partition>명령을 실행한다. 선택된 백엔드 로그와 파티션 내용으로 결과를 검증하고, 앞 단계 download 성공과 구분한다.
PRIMARY REFERENCES