2026-06-02

HID Report Descriptor 디버깅: 디바이스는 enumerate되지만 host가 잘못된 데이터를 읽는 이유

USB 장치가 정상 열거되지만 호스트에서 잘못 동작하게 만드는 HID 보고서 디스크립터 오류를 진단하는 방법입니다.

HID는 custom driver 없이도 동작할 수 있는 디바이스가 많기 때문에 매력적입니다. keyboard, sensor, knob, barcode reader, control panel, vendor-specific HID device는 모두 standard host stack의 이점을 얻습니다. 하지만 HID는 복잡성을 report descriptor 안으로 옮깁니다. 디바이스가 정상적으로 enumerate되어도 host가 데이터를 잘못 해석할 수 있습니다.

이는 USB firmware에서 가장 흔한 함정 중 하나입니다. enumeration 성공을 HID가 올바르다는 증거로 착각하는 것입니다.

Report Descriptor가 데이터 계약을 정의합니다

HID report descriptor는 host가 byte를 어떻게 해석해야 하는지 알려줍니다. usage, report size, report count, logical range, physical range, collection, report ID를 정의합니다. descriptor가 말하는 내용과 firmware가 보내는 내용이 다르면 host는 descriptor를 따릅니다.

흔한 문제는 다음과 같습니다.

firmware는 8 byte를 보내지만 descriptor는 7 byte를 설명함
report ID가 없거나 하나 더 있음
signed value가 unsigned로 설명됨
logical min/max가 실제 범위와 맞지 않음
usage page가 잘못됨
padding bit count가 잘못 계산됨
여러 report가 혼란스러운 layout을 공유함
input report와 output report가 뒤섞임

증상은 application에서 잘못된 값, 사라진 button, 무시되는 report, 간헐적 read처럼 나타날 수 있습니다.

Descriptor와 Report를 함께 캡처하십시오

report descriptor만 보고 HID를 디버깅하는 것은 불완전합니다. payload byte만 보고 디버깅하는 것도 불완전합니다. 둘 다 필요합니다.

유용한 HID capture에는 다음이 포함됩니다.

device descriptor
configuration 및 interface descriptor
HID descriptor
report descriptor request와 response
interrupt IN report
사용하는 경우 interrupt OUT report
feature report용 control transfer
report ID와 payload length

그다음 엔지니어는 선언된 layout과 실제 byte를 비교할 수 있습니다. report descriptor가 Report Count 3이라고 말하는데 interrupt payload가 네 개의 값을 담고 있다면, capture가 그 차이를 보이게 해야 합니다.

이상해 보여도 Host 동작은 올바를 수 있습니다

firmware 개발자는 host가 데이터를 버린다고 생각할 때가 있습니다. 실제로는 host가 받은 descriptor에 따라 parsing하고 있을 수 있습니다. descriptor가 padding이나 다른 report ID를 선언하면 데이터가 밀리거나 잘리거나 무시되는 것처럼 보일 수 있습니다.

그래서 좋은 support report에는 raw byte가 포함되어야 합니다. decoding된 해석은 유용하지만, raw byte가 논쟁을 끝냅니다. 질문은 이렇게 바뀝니다.

firmware가 무엇을 보냈는가?
firmware가 무엇을 선언했는가?
host가 무엇을 요청했는가?
host가 무엇을 받았는가?

이것이 HID 디버깅에 맞는 경계입니다.

Composite HID Device는 더 조심해야 합니다

Composite device는 HID와 함께 CDC, storage 또는 vendor-specific interface를 노출할 수 있습니다. HID 부분 자체는 맞더라도 interface numbering, endpoint assignment, descriptor total length error의 영향을 받을 수 있습니다.

Composite HID 디버깅에서는 다음을 확인하십시오.

해당되는 경우 interface association
interface number
endpoint address uniqueness
HID descriptor 위치
report descriptor length
class-specific request routing

host가 잘못된 interface에서 report descriptor를 요청하거나 잘못된 length를 받으면, 이후 report traffic은 오해를 부릅니다.

Bus Scope가 들어맞는 지점

Bus Scope는 firmware 및 device 팀이 증거 중심 USB 디버깅을 하도록 설계되었습니다. HID report descriptor case에서는 엔지니어가 descriptor tree, raw byte, endpoint traffic, 저장된 .bscope session을 함께 검사할 수 있어야 합니다.

실용적인 결과는 다음과 같이 말하는 report여야 합니다.

HID report descriptor가 요청되고 반환됨
descriptor가 선언한 report length
실제 interrupt payload length
report ID 동작
선언과 traffic 사이의 mismatch 또는 consistency
firmware descriptor, report packing 또는 host parser expectation에서의 다음 조치

이는 "HID device가 동작하지 않음"보다 훨씬 유용합니다. 막연한 input 문제를 구체적인 USB 계약 mismatch로 바꿉니다.

“HID Report Descriptor 디버깅: 디바이스는 enumerate되지만 host가 잘못된 데이터를 읽는 이유”의 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 Report Descriptor 디버깅: 디바이스는 enumerate되지만 host가 잘못된 데이터를 읽는 이유”에 대한 짧은 답은 다음과 같습니다. USB 장치가 정상 열거되지만 호스트에서 잘못 동작하게 만드는 HID 보고서 디스크립터 오류를 진단하는 방법입니다. 이 문장을 모든 입력, 장치, 프로젝트, 환경에 대한 약속이 아니라 검증할 결과로 다루십시오. 완료된 결과에는 시작 상태, 정확한 작업, 보이는 출력, Bus Scope에서 작업이 끝났음을 증명하는 조건이 기록됩니다.

근거 우선 작업 절차

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

확인점 1: HID Report Descriptor 디버깅: 디바이스는 enumerate되지만 host가 잘못된 데이터를 읽는 이유

“HID Report Descriptor 디버깅: 디바이스는 enumerate되지만 host가 잘못된 데이터를 읽는 이유”은 가장 작고 대표적인 입력으로 검증합니다. 관련 없는 설정은 유지하고 같은 작업을 반복하며 다시 열거나 연결한 뒤에도 결과가 유지되는지 확인합니다. 한 장의 화면보다 입력, 설정, 작업, 출력, 시간이 포함된 기록이 강합니다.

확인점 2: USB 장치가 정상 열거되지만 호스트에서 잘못 동작하게 만드는 HID 보고서 디스크립터 오류를 진단하는 방법입니다.

“USB 장치가 정상 열거되지만 호스트에서 잘못 동작하게 만드는 HID 보고서 디스크립터 오류를 진단하는 방법입니다.”이 모호하면 조건을 맞춘 정상 사례와 실패 사례를 비교합니다. 이후의 모든 증상보다 처음 나타난 의미 있는 차이를 표시하십시오. 이 경계가 더 명확한 지원 요청과 안전한 다음 실험을 만듭니다.

확인점 3: Report Descriptor가 데이터 계약을 정의합니다

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

확인점 4: Descriptor와 Report를 함께 캡처하십시오

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

확인점 5: 이상해 보여도 Host 동작은 올바를 수 있습니다

“이상해 보여도 Host 동작은 올바를 수 있습니다”은 가장 작고 대표적인 입력으로 검증합니다. 관련 없는 설정은 유지하고 같은 작업을 반복하며 다시 열거나 연결한 뒤에도 결과가 유지되는지 확인합니다. 한 장의 화면보다 입력, 설정, 작업, 출력, 시간이 포함된 기록이 강합니다.

확인점 6: Composite HID Device는 더 조심해야 합니다

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

확인점 7: Bus Scope가 들어맞는 지점

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

확인점 8: “HID Report Descriptor 디버깅: 디바이스는 enumerate되지만 host가 잘못된 데이터를 읽는 이유”의 USB 계약 시험

““HID Report Descriptor 디버깅: 디바이스는 enumerate되지만 host가 잘못된 데이터를 읽는 이유”의 USB 계약 시험”이 모호하면 조건을 맞춘 정상 사례와 실패 사례를 비교합니다. 이후의 모든 증상보다 처음 나타난 의미 있는 차이를 표시하십시오. 이 경계가 더 명확한 지원 요청과 안전한 다음 실험을 만듭니다.

확인점 9: 인용 가능한 답

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

확인점 10: firmware는 8 byte를 보내지만 descriptor는 7 byte를 설명함

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

인수 매트릭스

확인점	보존할 근거	통과 조건
HID Report Descriptor 디버깅: 디바이스는 enumerate되지만 host가 잘못된 데이터를 읽는 이유	시작 상태, 한 작업, 결과 상태	두 번째 담당자가 같은 결과를 재현한다
USB 장치가 정상 열거되지만 호스트에서 잘못 동작하게 만드는 HID 보고서 디스크립터 오류를 진단하는 방법입니다.	시작 상태, 한 작업, 결과 상태	두 번째 담당자가 같은 결과를 재현한다
Report Descriptor가 데이터 계약을 정의합니다	시작 상태, 한 작업, 결과 상태	두 번째 담당자가 같은 결과를 재현한다
Descriptor와 Report를 함께 캡처하십시오	시작 상태, 한 작업, 결과 상태	두 번째 담당자가 같은 결과를 재현한다
이상해 보여도 Host 동작은 올바를 수 있습니다	시작 상태, 한 작업, 결과 상태	두 번째 담당자가 같은 결과를 재현한다
Composite HID Device는 더 조심해야 합니다	시작 상태, 한 작업, 결과 상태	두 번째 담당자가 같은 결과를 재현한다

실패 분리, 복구, 인계

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

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

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

질문과 답변

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

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

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

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

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

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

언제 인계할 수 있습니까?

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