USB_Descriptor

USB 記述子

• AVR DU 系列の USB 周辺機能実装
• USB 2.0 制御エニュメレーション
• USB 記述子 本記事

GET_DESCRIPTOR

この 装置要求は、さまざまな構成記述子（ディスクリプタ）の返答を要求する。USB エニュメレーションの根幹。EP0_SETUP の wValue に記述子種別と指示指標番号、wIndex に 0または言語ID、wLength に返却すべき DATA長が格納されている。

wLength は、実際の 装置構成記述子 の大きさも少ないことがありうる。その際は 装置構成記述子 の先頭から、指定された長さだけを返答しなければならない。

if (bRequest == USB_REQ_GetDescriptor) {  /* 0x06 */
  size_t _length = (size_t)memcpy_descriptor(&EP0_IN_BUFF, EP0_SETUP.wValue);
  EP0_IN.CNT = EP0_SETUP.wLength < _length ? EP0_SETUP.wLength : _length;
  EP0_IN_flush();
}

wValue は、上位バイトに 記述子種別、下位バイトに その記述子に対する 指標番号 が格納されている。

Bit	Selector	Description
15-8	記述子種別	bDescriptorType
7-0	指標番号	iConfiguration etc.

記述子（ディスクリプタ構造体）の先頭 2バイトは、常に以下の情報を持つ。故に bLength の最小値は 2である。ホストはこの bLength を読み取って、2回目の GET_DESCRIPTOR 要求で 記述子全体を求める。

Ofs	Size	Field	Type	Description
0	1	bLength	数値	記述子全体長 0x02-0xFF
1	1	bDescriptorType	定数	記述子種別値

• bLength が固定長の列挙子であるなら GET_DESCRIPTOR 要求は 1回で求まる。そうでなければ長さ不定なので、2回の GET_DESCRIPTOR 要求で求められる。

bDescriptorType

記述子種別値 には以下の種類がある。一般に 0x01,0x02,0x04,0x05 の対応は必須。

bDescriptorType	Type	bLength	Description
0x01	DEVICE	18	必須
0x02	CONFIGURATION	9	ひとつ以上必須
0x03	STRING		任意
0x04	INTERFACE	9	ひとつ以上必須
0x05	ENDPOINT	7	エンドポイント0以外必須
0x06	DEVICE_QUALIFIER		Hi-Speed (USB 2.0 のみ)
0x07	OTHER_SPEED_CONFIGURATION		Hi-Speed (USB 2.0 のみ)
0x08	INTERFACE_POWER		(Deprecated)
0x09	OTG		OTG サポート
0x0B	INTERFACE_ASSOCIATION		IAD サポート
0x0F	BOS		USB 2.1 以降
0x10	DEVICE_CAPABILITY		USB 2.1 BOS
0x30	SUPERSPEED_USB_ENDPOINT_COMPANION		USB 3.0 Super-Speed

• 例えば DFU（Device Firmware Update）プロトコルは エンドポイント0 だけで実装されるため、エンドポイント記述子を実装していない。
• USB 2.0 の場合、Low/Full-Speed 装置であっても DEVICE_QUALIFIER 記述子は呼ばれるため、応答を返す必要がある。

0x20 以降は クラス固有定義（Class-Specific）で、bDeviceClass と組み合わせることで同じ種別値が使い回される。

Class	bDescriptorType	Type
HID	0x21	HID
	0x22	HID_REPORT
	0x23	HID_PHYSICAL
CS	0x21	CS_DEVICE
	0x22	CS_CONFIGURATION
	0x23	CS_STRING
	0x24	CS_INTERFACE
	0x25	CS_ENDPOINT
HUB	0x29	HUB

• BOS - Binary Device Object Store
• CDC - Communication Device Class
• ECN - Engineering Change Notice
• HID - Human Interface Device
• IAD - Interface Association Descriptor
• OTG - USB On-The-Go
• UAC - USB Audio Class
• UVC - USB Video Class

装置記述子 Device Descriptor

装置記述子は USB装置全体の基本情報を表明し、列挙子木の根として ただひとつが定義される。bDescriptorTypeは 0x01。全長bLengthは 18バイト（0x12）固定。

Ofs	Size	Field	Type	Description
0	1	bLength	数値	記述子全体長（0x12）
1	1	bDescriptorType	定数	記述子種別値（0x01）DEVICE
2	2	bcdUSB	BCD	装置が適合する USB版番号
4	1	bDeviceClass	クラス符号	USB協会で規約された基本クラス符号
5	1	bDeviceSubClass	補助クラス符号	USB協会で規約された補助クラス符号
6	1	bDeviceProtocol	規約符号	USB協会で規約された規約符号
7	1	bMaxPacketSize	数値	エンドポイント0のデータ長
8	2	idVendor	識別符号	USB協会定義の供給者識別符号（VID）
10	2	idProduct	識別符号	供給者定義の製品識別符号（PID）
12	2	bcdDevice	BCD	装置版番号
14	1	iManufacturer	指標番号	製造者識別記述を指す指標番号
15	1	iProduct	指標番号	製品識別記述を指す指標番号
16	1	iSerialNumber	指標番号	製品通版記述を指す指標番号
17	1	bNumConfigurations	数値	使用可能な構成記述数

bcdUSB

4桁の BCD 値。リトルエンディアン。

Version	Value	Description
USB 1.0	0x0100	（非推奨）
USB 1.1	0x0101	1.0 Minor Fix
USB 2.0	0x0200
USB 3.0	0x0300

• USB 1.1 は、従前の曖昧な仕様の厳格化を図っただけなので、実質 1.0 と変わりがない。
• USB 2.1 は、UVC 仕様の改善や Microsoft 独自拡張の公知を含んだりするが、版番号は 0x200 で変わらない。
• AVR DU系統では USB 2.0 を名乗れば問題ない。ソフトウェア的に USB 1.1 を名乗っても構わないが、エンドポイントペイロード長 wMaxPacketSize が制限される。

bDeviceClass

予約値の 0x00 と 0xFF 以外は、USB協会によって予約されている。ベンダー固有符号 は OS標準ドライバ以外を必要とすることを示す。

基本クラス符号／補助クラス符号／規約符号の組み合わせは USB-IF Defined Class Codes を参照。

bDeviceClass	Descriptor	Description
0x00	Device	インタフェース記述子の bInterfaceClass に依存
0x01	Interface	USB Audio Class (UAC)
0x02	Both	Communication Device Class (CDC)
0x03	Interface	Human Interface Device Class (HID)
0x05	Interface	Physical
0x06	Interface	Still Imaging
0x07	Interface	Printer
0x08	Interface	Mass Storage/SCSI Class (MDC)
0x09	Device	HUB Class (HUB)
0x0A	Interface	Communications-Data (CDC)
0x0B	Interface	Smart Card
0x0D	Interface	Content Security
0x0E	Interface	USB Video Class (UVC)
0x0F	Interface	Personal Healthcare
0x10	Intreface	Audio/Video Devices
0x11	Device	Billboard Device Class (BDC)
0x12	Intreface	USB Type-C Bridge Class
0x13	Intreface	USB Bulk Display Protocol Device Class
0x14	Intreface	MCTP over USB Protocol Endpoint Device Class
0x3C	Intreface	I3C Device Class
0xDC	Both	Diagnostic Device
0xE0	Intreface	Wireless Controller
0xEF	Both	Miscellaneous
0xFE	Intreface	Application Specific (DFU etc)
0xFF	Both	ベンダー固有クラス符号

• クラス符号 0x00 は、インタフェース記述子の bInterfaceClass を参照することを指定する。
• クラス符号 0xFF は、ベンダー固有クラス符号であって、専用のドライバによって制御されることを示す。

bDeviceSubClass

予約値の 0x00 と 0xFF 以外は、USB協会によって予約されている。ベンダー固有符号 は OS標準ドライバ以外を必要とすることを示す。

bDeviceClass	Name	Description
0x00	undefined	インタフェース記述子 bInterfaceSubClass に依存
0xFF	VENDOR	ベンダー固有補助クラス符号

• 補助クラス符号 0x00 は、インタフェース記述子の bInterfaceSubClass を参照することを指定する。
• 補助クラス符号 0xFF は、ベンダー固有補助クラス符号であって、専用のドライバによって制御されることを示す。

bDeviceProtocol

予約値の 0x00 と 0xFF 以外は、USB協会によって予約されている。ベンダー固有符号 は OS標準ドライバ以外を必要とすることを示す。

bDeviceClass	Name	Description
0x00	undefined	インタフェース記述子 bInterfaceProtocol に依存
0xFF	VENDOR	ベンダー固有プロトコル符号

• 補助クラス符号 0x00 は、インタフェース記述子の bInterfaceProtocol を参照することを指定する。
• 補助クラス符号 0xFF は、ベンダー固有規約符号であって、専用のドライバによって制御されることを示す。

bMaxPacketSize

エンドポイント0 のデータ長を指定する。bcdUSB の記述によって許される最大値が異なる。

bcdUSB	Value
0x01xx	8
0x0200 以上	8,16,32,64

• エンドポイント0 については、実装されることが絶対条件なのでこれ以外の設定は必要とされず、対応するエンドポイント記述子も存在しない。

idVendor / idProduct

いずれも 16ビット無符号整数。一般にこの組は、ベンダー固有ドライバの読み込み識別符号と認識される。

bcdDevice

任意の 2桁の BCD値。OS標準ドライバからは、OSの装置プロパティに表示する以上の役割はない。

iManufacturer / iProduct / iSerialNumber

いずれも特定の 文字列記述子 を示す指標番号（Index）で、未使用なら 0x00 とする。採番は 0x00 以外は実装都合で良く、必ずしも連番である必要はない。

bNumConfigurations

0x01 以上の、装置で支援される 構成記述子の数。普通は 0x00 ではありえない。

構成記述子 Configuration Descriptor

構成記述子は 装置記述子の下位に連なる列挙子木の枝葉として ひとつ以上が定義される。bDescriptorType は 0x02。全長bLengthは 9バイト（0x09）固定。

装置記述子は全体でひとつしか存在できないが、構成記述子は複数持つことができる。それぞれが異なるインタフェース記述子（とエンドポイント記述子）をまとめることができ、異なる電力形態を定義することができる。

• しかしながら現実的には複数の構成記述子を持つ実装需要はそう多くなく、単一の構成記述子と複数のインタフェース記述子の組を持つことがほとんどだろう。数少ない需要には、複数のアップストリームポートを持つ KVM や OTG 機器がありうる。

Ofs	Size	Field	Type	Description
0	1	bLength	数値	記述子全体長（0x09）
1	1	bDescriptorType	定数	記述子種別値（0x02）CONFIGURATION
2	2	wTotalLength	数値	この構成に含まれる全記述子の総バイト数
4	1	bNumInterfaces	数値	この構成に含まれるインターフェース数
5	1	bConfigurationValue	数値	この構成を特定する指標番号
6	1	iConfiguration	指標番号	この記述子を説明する文字列記述子指標番号
7	1	bmAttributes	ビット定義	（後述）
8	1	bMaxPower	数値	2mA単位の最大要求電流（0x01-0xFA）

wTotalLength

この構成に含まれる全記述子の総バイト数。つまり General Configuration Descriptor 全体構成要求（GCD）で必要になるバイト長。これには 装置記述子 は含まれない。分からなければ 0を書く。

この値が設定されている場合、General Configuration Descriptor 全体構成要求（GCD）が生じる場合がありうる。この場合この構成に含まれる（つまり装置記述子を除く）全ての インタフェース記述子、エンドポイント記述子を、構成記述子 の後方にまとめて連結して一回で転送することができ、エニュメレーションが効率化される。これに含まれない（文字列等の）記述子、あるいは GCD に含めても認識されなかった記述子は、あとから個別に要求されることになる。逆にこの要求でないとホストに通知できない種別の記述子もありうる。この GCD 要求は bLength に代えて wTotalLength が EP0_SETUP.wLength に示されていることで区別できる。（bLength < wLength）

• つまり最大効率のエニュメレーションは、Set Address 指令、Device Descriptor 装置要求、Configuration Descriptor 構成の先頭 4バイト要求、General Configuration Descriptor 全体構成要求で完了する。

bNumInterfaces

この構成に含まれるインターフェース記述子の数。普通は 0x00 ではありえない。

bConfigurationValue

この構成を特定する指標番号。採番は 0x00 以外は実装都合で良い。

指標番号は必ずしも連番である必要はない。例えば bDescriptorType や bString で使用されない空番に指標番号を割り当てると、すべての記述子を単一のアドレス参照テーブルで列挙して管理（memcpyで複写等）することが容易になる。

iConfiguration

この構成を説明する識別記述を指す指標番号（Index）で、未使用なら 0x00 とする。実体は 文字列記述子 として取得される。

bmAttributes

この属性は、この構成の電力形態を表明する。対応する電力形態切替は 装置要求 SET_FEATURE で指定される。

Bit	Selector	Value	Description
7	BUS_POWERED	0/1	バス給電対応
6	SELF_POWERED	0/1	自己給電対応
5	REMOTE_WAKEUP	0/1	遠隔起動許可

bMaxPower

USB 2.0 までは、装置の バス給電での最大要求電流を 2mA 単位で表明する。最小値は 0x01、最大値は（500mA 迄なので）0xFA である。

• あくまでも要求値であって、ホストから確実にそこまで供給される保証はない。途中に USBハブが介在していればなおさらである。
• USB 3.0 以降は 8mA 単位で指定するよう変更され、バス給電機器は 最大 900mA（0x70）まで要求可能。

文字列記述子 String Descriptor

この記述子は iManufacturer,iProduct,iSerialNumber,iConfiguration,iInterface 等から間接的に参照される。参照される指標番号は、0x00 については装置が 支援可能な 言語識別ID のカタログ要求となり、そうでなければ UTF-16 符号化文字列実体の要求となる。

wLANGID

言語識別ID カタログ（文字列記述子指標番号0）は、ひとつ以上の wLANGID を格納する。

Ofs	Size	Field	Type	Description
0	1	bLength	数値	記述子全体長（2n+2）
1	1	bDescriptorType	定数	記述子種別値（0x03）STRING
2	2	wLANGID[0]	言語識別ID	支援する言語番号0の識別ID
...	..	...	...	...
2n+2	2	wLANGID[n]	言語識別ID	支援する言語番号nの識別ID

wLANGID	Description
0x0409	英語（米国）
0x0411	日本語
0x04FF	HIDデータ記述子用
0xF0FF	HID供給者定義1
0xF4FF	HID供給者定義2
0xF8FF	HID供給者定義3
0xFEFF	HID供給者定義4

bString

符号化文字列（文字列記述子指標番号0以外）には、UTF-16 で符号化された文字列を格納する。符号化された 1文字は常に 2バイトなので、必ず 2の倍数長となる。

Ofs	Size	Field	Type	Description
0	1	bLength	数値	記述子全体長（2n+2）
1	1	bDescriptorType	定数	記述子種別値（0x03）STRING
2	2n	bString	UTF-16	符号化された文字列

選択されるべき言語識別ID は、EP0_SETUP.wIndex で指定される。言語識別ID カタログ で ただ一種の wLANGID（普遍的には 0x0409）を支援するのなら無視して良い。

指標番号は 常に 0x00 以外となるが、必ずしも連番である必要はない。例えば bDescriptorType や bConfigurationValue で使用されない空番に指標番号を割り当てると、すべての記述子を単一のアドレス参照テーブルで列挙して管理することが容易になる。

インターフェース記述子 Interface Descriptor

インターフェース記述子は 構成記述子の下位に連なる列挙子木の枝葉として ひとつ以上が定義される。bDescriptorType は 0x04。全長bLengthは 9バイト（0x09）固定。

Ofs	Size	Field	Type	Description
0	1	bLength	数値	記述子全体長（0x09）
1	1	bDescriptorType	定数	記述子種別値（0x04）INTERFACE
2	1	bInterfaceNumber	数値	インターフェース番号
3	1	bAlternateSetting	数値	代替インタフェース番号
4	1	bNumEndpoints	数値	このインタフェースで使用されるエンドポイント数
5	1	bInterfaceClass	クラス符号	USB協会で規約されたクラス符号
6	1	bInterfaceSubClass	補助クラス符号	USB協会で規約された補助クラス符号
7	1	bInterfaceProtocol	規約符号	USB協会で規約された規約符号
8	1	iInterface	指標番号	この記述子を説明する文字列記述子指標番号

bInterfaceNumber

このインターフェース記述子の指標番号を表す。0x00 ではありえない。採番は必ずしも連番である必要はない。

bAlternateSetting

このインタフェース記述子に代えて、代替可能な記述子を示す指標番号。0x00 とすると代替選択不可となる。

bNumEndpoints

このインタフェースで使用されるエンドポイントの数。普通は 0x00 ではありえないが、例外もある。

bInterfaceClass

bDeviceClass を参照。

bInterfaceSubClass

bDeviceSubClass を参照。

bInterfaceProtocol

bDeviceProtocol を参照。

iInterface

このインタフェース記述子を説明する識別記述を指す指標番号（Index）で、未使用なら 0x00 とする。実体は 文字列記述子 として取得される。

エンドポイント記述子 Endpoint Descriptor

エンドポイント記述子は 構成記述子の下位に連なる列挙子木の枝葉として ひとつ以上が定義される。bDescriptorType は 0x05。全長bLengthは 7バイト（0x07）固定。

Ofs	Size	Field	Type	Description
0	1	bLength	数値	記述子全体長（0x07）
1	1	bDescriptorType	定数	記述子種別値（0x05）ENDPOINT
2	1	bEndpointAddress	ビット定義	（後述）
3	1	bmAttributes	ビット定義	（後述）
4	2	wMaxPacketSize	数値	このエンドポイントのペイロード長
6	1	bInterval	数値	エンドポイント調査間隔

bEndpointAddress

このエンドポイントの番号と方向を指示する。標準エンドポイント要求 の wIndex 下位バイトに反映される。

Bit	Selector	Value	Description
7	転送方向	0	ホスト⇨装置（OUT）
		1	装置⇨ホスト（IN）
6-4	予約	0
3-0	EP番号	0-15

• EP0 用の エンドポイント記述子 は不要。
• AVR DU系統のエンドポイント仮想レジスタ群アドレスとは、上下ニブルを入れ換えることで一致する。

bmAttributes

このエンドポイントの性質を通知する。等時（Isochronous）転送用のみ、Bit[5-2] を使用する。

Bit	Selector	Value	Description
7,6	予約	0
5,4	使用種別	11	予約
		10	明示的逆走EP
		01	暗黙的逆走EP
		00	通常EP
3,2	同期種別	11	同期
		10	適応
		01	非同期
		00	同期なし
1,0	転送種別	01	等時（Isochronous）

Bit	Selector	Value	Description
7-2	予約	0
1,0	転送種別	11	割込（Interrupt）
		10	大量（Bulk）
		00	制御（Control）

wMaxPacketSize

当該エンドポイントの ペイロード長をバイト単位で指定する。Bit[10-0] が有効。エンドポイントの性質によって許される値が異なる。

Type	USB 3.0 SS	USB 2.0 HS	USB 1.1 FS	USB 1.1 LS
Control	512	64	8,16,32,64	8
Bulk	1023	512	8,16,32,64	-
Interrupt	0-1024	0-1024	0-64	8
Isochronous	0-1024	0-1024	0-1023	-

• Bit[15-11] は予約されており、0とすべき。広帯域エンドポイント拡張仕様（USB 2.0 High-Speed, High Bandwidth Endpoint）で使用される。

bInterval

当該エンドポイントが 割込 または 等時転送 である場合の、ホスト側からのポーリング間隔。速度によって粒度と計算方法が異なる。制御 または 大量転送では 使われないので常に 0を書く。

Type	Low-Speed	Full-Speed	High-Speed
Interrupt	10-255[1ms]	1-255[1ms]	1-16 ⇨ 2のn-1乗[125us]
Isochronous	-	1-16 ⇨ 2のn-1乗[1ms]	1-16 ⇨ 2のn-1乗[125us]

Isochronous	1	2	3	...	16
x 1ms (FS)	1	2	4	...	32768
x 1us (HS)	125	250	500	...	4096000

さらにホストOS（特に Windows）のドライバによって、実際に適用されるポーリング間隔が丸め込まれる。

Low-Speed	0-15	16-35	36-255
x 1ms	8	16	32

Full-Speed	1	2-3	4-7	8-15	16-31	32-255
x 1ms	1	2	4	8	16	32

• https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/usbspec/ns-usbspec-_usb_endpoint_descriptor

構成修飾記述子 Device Qualifier Descriptor

構成修飾記述子は、装置の通信速度を変更できるときに要求される。bDescriptorType は 0x06。全長bLengthは 10バイト（0x0A）固定。

現在選択されている速度そのままで通信を継続する（あるいは速度変更に対応しない）装置ではこれを無視して ZLPを返せば良い。記述子の内容は 装置記述子に似ており、オフセット 8から 16の 9バイトが抜かれ、最後に予約バイトを付加している。

Ofs	Size	Field	Type	Description
0	1	bLength	数値	記述子全体長（0x0A）
1	1	bDescriptorType	定数	記述子種別値（0x06）DEVICE_QUALIFIER
2	2	bcdUSB	BCD	装置が適合する USB版番号
4	1	bDeviceClass	クラス符号	USB協会で規約された基本クラス符号
5	1	bDeviceSubClass	補助クラス符号	USB協会で規約された補助クラス符号
6	1	bDeviceProtocol	規約符号	USB協会で規約された規約符号
7	1	bMaxPacketSize	数値	エンドポイント0のデータ長
8	1	bNumConfigurations	数値	使用可能な構成記述数
9	1	Reserved

• この構成修飾記述子は、General Configuration Descriptor 全体構成要求 に含めることができない。
• 装置の bcdUSB とホストの既定バージョンと合わないときは、1回は要求されるとみなして良い。
• 実際の対応速度や実装は、bNumConfigurations で示される 構成記述子 麾下の内容で決まる。

関連リンク

• USB-IF Defined Class Codes
• AVR329:USBファームウェア基本設計
• Microchip PIC & AVR Solutions / Github