2026-06-02

HID 및 CDC Device를 위한 USB Descriptor 디버깅

HID와 CDC device는 firmware team이 모든 host마다 custom driver를 작성하지 않고도 유용한 USB interface를 출시할 수 있게 해 주기 때문에 널리 쓰입니다.

HID와 CDC device는 firmware team이 모든 host마다 custom driver를 작성하지 않고도 유용한 USB interface를 출시할 수 있게 해 주기 때문에 널리 쓰입니다. 이 편의성은 descriptor가 정확하다는 전제 위에 있습니다. HID keyboard, sensor, serial bridge, composite device가 실패할 때 root cause는 application에 나타나기 전에 descriptor evidence에서 먼저 보이는 경우가 많습니다.

Descriptor debugging은 화려하지 않지만 USB support case를 해결하는 가장 빠른 방법 중 하나입니다.

HID: Report Descriptor가 contract입니다

HID device에서 host는 endpoint 정보 이상의 것을 필요로 합니다. HID report descriptor가 필요합니다. 이 descriptor는 report ID, usage, size, count, logical range, byte 해석 방식을 정의합니다.

흔한 HID 실수:

report length가 실제 interrupt payload와 맞지 않음
firmware에서 report ID를 사용하지만 일관되게 선언하지 않음
logical min/max 값이 data representation과 맞지 않음
usage page 또는 usage가 host expectation과 맞지 않음
endpoint interval이 device behavior에 비해 비현실적임
boot protocol 가정이 report protocol behavior와 충돌함

host error는 모호해 보일 수 있습니다. 하지만 descriptor byte와 interrupt transfer를 보여주는 capture는 mismatch를 명확하게 드러냅니다.

CDC: Interface layout이 중요합니다

CDC ACM device는 보통 communication interface와 data interface를 노출합니다. host는 일관된 descriptor set과 class-specific request를 기대합니다. functional descriptor 누락, 잘못된 interface association, endpoint mismatch는 virtual serial port가 나타나지 못하게 할 수 있습니다.

확인할 evidence:

serial port는 나타나지만 byte가 움직이지 않는다면 문제는 endpoint behavior 또는 application protocol일 수 있습니다. serial port가 전혀 나타나지 않는다면 descriptor와 class request를 먼저 봐야 합니다.

Composite device에는 더 엄격한 discipline이 필요합니다

Composite device는 HID, CDC, mass storage, vendor-specific interface 등을 결합할 수 있습니다. 유용하지만 failure mode가 늘어납니다. 한 interface의 descriptor mistake가 device 전체의 host binding에 영향을 줄 수 있습니다.

Composite debugging에서는 다음을 확인하십시오.

capture가 host가 올바른 구조를 봤다는 것을 증명하기 전까지는 "firmware가 올바른 byte를 보낸다"고 가정하지 마십시오.

Raw byte와 Class interpretation이 모두 중요한 이유

Raw byte는 ground truth입니다. Class interpretation은 그것을 사용할 수 있게 만듭니다. 좋은 USB diagnostic tool은 둘 다 보여야 합니다. engineer는 문제가 있을 때 정확한 descriptor byte를 봐야 하지만, 매번 offset을 손으로 세지 않도록 decoded field도 필요합니다.

가장 좋은 workflow는 다음과 같습니다.

decoded descriptor tree를 확인합니다.
의심스러운 field의 raw byte로 이동합니다.
host request와 firmware response를 비교합니다.
configuration 이후 endpoint transfer를 확인합니다.
reproduction 또는 support handoff를 위해 session을 저장합니다.

이 workflow는 진단을 evidence에 묶어 둡니다.

Bus Scope가 맞는 위치

Bus Scope는 USB traffic이 왜 실패하는지 반복 가능한 답이 필요한 firmware team, hardware lab, device vendor를 위해 설계되었습니다. device explorer context, packet detail, raw byte, descriptor, class observation, filter, 저장된 .bscope session을 하나의 workbench 안에 유지합니다.

HID와 CDC case에서 Bus Scope는 다음 질문에 답할 수 있어야 합니다.

enumeration이 완료되었는가?
descriptor가 의도한 class와 맞았는가?
host가 expected class request를 보냈는가?
endpoint transfer가 report 또는 line coding expectation과 맞았는가?
firmware, host driver, application protocol 중 어디의 문제인가?

이것이 "driver failed"를 보는 것과 어떤 USB contract가 깨졌는지 이해하는 것의 차이입니다.

“HID 및 CDC Device를 위한 USB Descriptor 디버깅”의 USB 계약 시험

직접적인 답은 STALL, timeout, reset 하나만으로 원인을 설명할 수 없다는 것입니다. 먼저 capture provider가 올바른 device를 보는지 증명하고 transfer 계약을 읽습니다. 종류, 방향, recipient, wValue, wIndex, 선언 길이, 실제 길이, status, 전후 상태를 확인하고 known-good과 처음 달라지는 transaction에 결론을 연결합니다.

경계	비교 근거	판단
platform	provider, 권한, Root Hub, usbmon/XHC20	올바른 연결의 record인가
setup	bmRequestType, bRequest, wValue, wIndex, wLength	host가 의도한 요청을 보냈는가
data	방향, 길이, 보존 bytes	payload가 계약과 맞는가
status	ACK, STALL, timeout, cancellation	transaction이 어디서 끝났는가
state	configuration, interface, alternate setting, halt	device가 요청을 받을 상태인가

reset과 enumeration 전부터 capture하여 descriptor, SET_CONFIGURATION, SET_INTERFACE, 실패 직전 command를 남깁니다. 좁은 endpoint filter는 결정적인 control transfer를 숨길 수 있습니다. 시험 한 번에는 문서화한 USB 동작 하나만 수행하고 firmware, driver, port, cable, host command, timing 중 하나만 바꿉니다.

인용 가능한 답

관찰한 request, setup field, 응답, 직전 상태를 쓰고 한 변수만 바꾸는 다음 시험을 제시합니다. retention 때문에 보존되지 않은 bytes는 packet loss 증명이 아닙니다. command와 reset의 시간적 근접은 상관관계이며 상태 전환이나 반복 없이 원인으로 단정할 수 없습니다.

VID/PID, firmware, speed, topology, provider, filter, trigger를 고정하고 usbmon과 USBPcap의 frame number 대신 USB 의미 단계로 비교합니다. 시작·종료, 버전, OS, 연결 위치, checksum을 기록하고 Bus Scope 문제 해결에서 검토합니다.

Semrush owner는 분리합니다. free USB analyzer는 제품 페이지, best USB protocol analyzer는 비교 페이지, USB descriptor viewer는 descriptor 안내가 담당합니다. 이 지원 글에 확인되지 않은 검색량이나 KD를 만들지 않습니다.

직접 답변과 인수 경계

“HID 및 CDC Device를 위한 USB Descriptor 디버깅”에 대한 짧은 답은 다음과 같습니다. HID와 CDC device는 firmware team이 모든 host마다 custom driver를 작성하지 않고도 유용한 USB interface를 출시할 수 있게 해 주기 때문에 널리 쓰입니다. 이 문장을 모든 입력, 장치, 프로젝트, 환경에 대한 약속이 아니라 검증할 결과로 다루십시오. 완료된 결과에는 시작 상태, 정확한 작업, 보이는 출력, Bus Scope에서 작업이 끝났음을 증명하는 조건이 기록됩니다.

근거 우선 작업 절차

전체 프로젝트를 바꾸기 전에 작고 반복 가능한 사례에서 시작하십시오. 앱 버전, 운영체제, 입력 또는 장치 식별, 관련 설정과 예상 결과를 기록합니다. 한 가지 의도적인 작업을 실행하고 첫 예상 밖 전환을 보존하며 가능한 경우 정상 사례와 비교합니다. 여러 설정을 동시에 바꾸면 문제를 만든 조건이나 해결한 조건을 알 수 없습니다.

확인점 1: HID 및 CDC Device를 위한 USB Descriptor 디버깅

“HID 및 CDC Device를 위한 USB Descriptor 디버깅”이 모호하면 조건을 맞춘 정상 사례와 실패 사례를 비교합니다. 이후의 모든 증상보다 처음 나타난 의미 있는 차이를 표시하십시오. 이 경계가 더 명확한 지원 요청과 안전한 다음 실험을 만듭니다.

확인점 2: HID와 CDC device는 firmware team이 모든 host마다 custom driver를 작성하지 않고도 유용한 USB interface를 출시할 수

“HID와 CDC device는 firmware team이 모든 host마다 custom driver를 작성하지 않고도 유용한 USB interface를 출시할 수 있게 해 주기 때문에 널리 쓰입니다.”은 가장 작고 대표적인 입력으로 검증합니다. 관련 없는 설정은 유지하고 같은 작업을 반복하며 다시 열거나 연결한 뒤에도 결과가 유지되는지 확인합니다. 한 장의 화면보다 입력, 설정, 작업, 출력, 시간이 포함된 기록이 강합니다.

확인점 3: HID: Report Descriptor가 contract입니다

“HID: Report Descriptor가 contract입니다”이 모호하면 조건을 맞춘 정상 사례와 실패 사례를 비교합니다. 이후의 모든 증상보다 처음 나타난 의미 있는 차이를 표시하십시오. 이 경계가 더 명확한 지원 요청과 안전한 다음 실험을 만듭니다.

확인점 4: CDC: Interface layout이 중요합니다

“CDC: Interface layout이 중요합니다”은 가장 작고 대표적인 입력으로 검증합니다. 관련 없는 설정은 유지하고 같은 작업을 반복하며 다시 열거나 연결한 뒤에도 결과가 유지되는지 확인합니다. 한 장의 화면보다 입력, 설정, 작업, 출력, 시간이 포함된 기록이 강합니다.

확인점 5: Composite device에는 더 엄격한 discipline이 필요합니다

“Composite device에는 더 엄격한 discipline이 필요합니다”이 모호하면 조건을 맞춘 정상 사례와 실패 사례를 비교합니다. 이후의 모든 증상보다 처음 나타난 의미 있는 차이를 표시하십시오. 이 경계가 더 명확한 지원 요청과 안전한 다음 실험을 만듭니다.

확인점 6: Raw byte와 Class interpretation이 모두 중요한 이유

“Raw byte와 Class interpretation이 모두 중요한 이유”은 가장 작고 대표적인 입력으로 검증합니다. 관련 없는 설정은 유지하고 같은 작업을 반복하며 다시 열거나 연결한 뒤에도 결과가 유지되는지 확인합니다. 한 장의 화면보다 입력, 설정, 작업, 출력, 시간이 포함된 기록이 강합니다.

확인점 7: Bus Scope가 맞는 위치

“Bus Scope가 맞는 위치”이 모호하면 조건을 맞춘 정상 사례와 실패 사례를 비교합니다. 이후의 모든 증상보다 처음 나타난 의미 있는 차이를 표시하십시오. 이 경계가 더 명확한 지원 요청과 안전한 다음 실험을 만듭니다.

확인점 8: “HID 및 CDC Device를 위한 USB Descriptor 디버깅”의 USB 계약 시험

““HID 및 CDC Device를 위한 USB Descriptor 디버깅”의 USB 계약 시험”은 가장 작고 대표적인 입력으로 검증합니다. 관련 없는 설정은 유지하고 같은 작업을 반복하며 다시 열거나 연결한 뒤에도 결과가 유지되는지 확인합니다. 한 장의 화면보다 입력, 설정, 작업, 출력, 시간이 포함된 기록이 강합니다.

확인점 9: 인용 가능한 답

“인용 가능한 답”이 모호하면 조건을 맞춘 정상 사례와 실패 사례를 비교합니다. 이후의 모든 증상보다 처음 나타난 의미 있는 차이를 표시하십시오. 이 경계가 더 명확한 지원 요청과 안전한 다음 실험을 만듭니다.

확인점 10: report length가 실제 interrupt payload와 맞지 않음

“report length가 실제 interrupt payload와 맞지 않음”은 가장 작고 대표적인 입력으로 검증합니다. 관련 없는 설정은 유지하고 같은 작업을 반복하며 다시 열거나 연결한 뒤에도 결과가 유지되는지 확인합니다. 한 장의 화면보다 입력, 설정, 작업, 출력, 시간이 포함된 기록이 강합니다.

인수 매트릭스

확인점	보존할 근거	통과 조건
HID 및 CDC Device를 위한 USB Descriptor 디버깅	시작 상태, 한 작업, 결과 상태	두 번째 담당자가 같은 결과를 재현한다
HID와 CDC device는 firmware team이 모든 host마다 custom driver를 작성하지 않고도 유용한 USB interface를 출시할 수 있게 해 주기 때문에 널리 쓰입니다.	시작 상태, 한 작업, 결과 상태	두 번째 담당자가 같은 결과를 재현한다
HID: Report Descriptor가 contract입니다	시작 상태, 한 작업, 결과 상태	두 번째 담당자가 같은 결과를 재현한다
CDC: Interface layout이 중요합니다	시작 상태, 한 작업, 결과 상태	두 번째 담당자가 같은 결과를 재현한다
Composite device에는 더 엄격한 discipline이 필요합니다	시작 상태, 한 작업, 결과 상태	두 번째 담당자가 같은 결과를 재현한다
Raw byte와 Class interpretation이 모두 중요한 이유	시작 상태, 한 작업, 결과 상태	두 번째 담당자가 같은 결과를 재현한다

실패 분리, 복구, 인계

처음 실패한 경계에서 멈추십시오. 소스, 프로젝트, 세션 또는 캡처를 보존하고 파괴적 편집 전에 복사하며 실험마다 한 변수만 변경합니다. 여러 변경 뒤 전체 흐름을 반복해 결과가 달라져도 원인은 설명되지 않습니다.

근거가 없는 것과 없다는 근거를 구분하십시오. 빈 화면은 잘못된 입력, 범위, 필터, 권한, 장치, 시간대 또는 프로젝트 상태일 수 있습니다. decoder, 편집기, 보고서, 내보내기를 해석하기 전에 획득 또는 가져오기 경로를 확인합니다.

인계 전에 결과물을 다시 열어 시작, 판단 지점, 끝을 확인합니다. 버전, 플랫폼, 설정, 기대, 관찰, 최소 재현을 기록합니다. 민감한 내용을 제거하거나 가리고 수신자의 권한을 확인합니다.

질문과 답변

가장 빠르고 신뢰할 수 있는 시작 방법은 무엇입니까?

가장 작고 대표적인 사례를 사용하고 예상 결과를 적은 뒤 한 변수만 바꿉니다. 필터, 효과, 편집, 자동화 또는 큰 소스를 추가하기 전에 기본 경로를 확인합니다.

어떤 근거를 저장해야 합니까?

입력 식별, 버전, 플랫폼, 설정, 정확한 작업, 첫 예상 밖 전환, 최종 출력을 보존합니다. 프로젝트, 세션, 보고서 또는 내보내기는 닫고 다시 열어 확인합니다.

언제 절차를 반복해야 합니까?

앱, 운영체제, driver, firmware, 모델, 소스 또는 작업 흐름의 변경이 결과에 영향을 줄 수 있을 때입니다. 이전에 통과한 사례를 변경하지 않은 기준선으로 유지합니다.

언제 인계할 수 있습니까?

권한 있는 다른 사람이 입력을 식별하고 작업을 반복하여 같은 결과를 보고 남은 제한을 이해하며 기록되지 않은 로컬 상태 없이 결과물을 열 수 있을 때입니다.