高性能 USB スタック
USBX ホストスタック・ユーザガイド
Express Logic
858.613.6640 Toll Free 888.THREADX FAX
858.521.4259 http://www.expresslogic.com
©1999-2014 by Express Logic, Inc.
All rights reserved.This document and the associated USBX software are the sole property of Express Logic, Inc. Each contains proprietary information of Express Logic, Inc. Reproduction or duplication by any means of any portion of this document without the prior written consent of Express Logic, Inc. is expressly forbidden.
Express Logic, Inc.は、USBX の設計または信頼性を向上するために、随時に予告なく、本書に記 載する仕様を変更する権利を留保します。本書の内容については万全を期していますが、本書の正 確性について Express Logic, Inc.が保証するものではありません。
商標
FileX および ThreadX は Express Logic, Inc.の登録商標であり、USBX、NetX、picokernel、 preemption-threshold、event-chaining は、Express Logic, Inc.の商標です。
保証の制限
Express Logic, Inc.は、USBX 製品が使用者の要件を満たすもしくは使用者により指定されたとおり に動作すること、USBX 製品が中断もしくは欠陥なしに動作すること、または USBX 製品に見つかる いかなる欠陥も保障期間後に補正されることにつき、一切保証するものではありません。Express Logic, Inc.は USBX 製品に関し、市場性および特定の目的への適合性を含めて、明示あるいは黙 示を問わず一切責任を負わないものとします。Express Logic, Inc.、そのディーラ、販売店、代理店 または従業員から口頭もしくは書面で情報または助言が与えられた場合、それにより、他の保証が 生じるものでもなく、またこの保証の範囲がいかなる形であれ拡大するものでもありません。また、ラ イセンス取得者はそのような情報または助言に依拠してはなりません。
パート番号: 000-1010 改訂 5.7 版
目次
目次 ... 3
本書について ... 6
第 1 章
USBX の概要 ... 7
USBX の機能 ... 7 製品ハイライト ... 8 USBX の強力なサービス ... 8 複数ホストコントローラのサポート ... 8 USB ソフトウェアスケジューラ ... 8 USB デバイスフレームワークの完全なサポート ... 8 使いやすい API ... 8第 2 章
USBX のインストール ... 10
ホストについて ... 10 コンピュータの種類 ... 10 ダウンロード用インタフェース ... 10 デバッグツール ... 10 必要なハードディスク容量 ... 10 ターゲットについて ... 10 コンフィギュレーションオプション ... 13 ソースコードツリー ... 15 USBX リソースの初期化 ... 16 USB ホストコントローラの定義 ... 17 ホストクラスの定義 ... 18 トラブルシューティング ... 20 USBX バージョン ID ... 20第 3 章
USBX ホストスタックのファンクション コンポーネント... 21
実行概要 ... 21 初期化 ... 22 アプリケーションインタフェースコール ... 22 USB ホストスタック API ... 22 USB ホストクラス API ... 22 ルートハブ ... 23 ハブクラス ... 23 USB ホストスタック ... 23トポロジマネージャ ... 23 USB クラスのバインド ... 23 USBX API ... 24 ホストコントローラ ... 24 ルートハブ ... 25 電力管理 ... 25 エンドポイント ... 25 転送 ... 25 USB デバイスのフレームワーク ... 26 デバイス記述子 ... 28 コンフィギュレーション記述子 ... 31 インタフェース記述子 ... 33 エンドポイント記述子... 36 ストリング記述子 ... 39 ファンクショナル記述子 ... 41 メモリ内の USBX デバイス記述子フレームワーク ... 41
第 4 章
USBX ホストサービスの説明 ... 43
ux_host_stack_initialize ... 44 ux_host_stack_endpoint_transfer_abort ... 45 ux_host_stack_class_get ... 46 ux_host_stack_class_register ... 47 ux_host_stack_class_instance_create ... 48 ux_host_stack_class_instance_destroy ... 49 ux_host_stack_class_instance_get ... 50 ux_host_stack_device_configuration_get ... 51 ux_host_stack_device_configuration_select ... 52 ux_host_stack_device_get ... 54 ux_host_stack_interface_endpoint_get ... 55 ux_host_stack_hcd_register ... 57 ux_host_stack_configuration_interface_get ... 59 ux_host_stack_interface_setting_select ... 60 ux_host_stack_transfer_request_abort ... 61 ux_host_stack_transfer_request ... 62第 5 章
USBX ホストクラスの API ... 64
ux_host_class_printer_read ... 65 ux_host_class_printer_write ... 66 ux_host_class_printer_soft_reset ... 67 ux_host_class_printer_status_get ... 68 ux_host_class_audio_read ... 69 ux_host_class_audio_write ... 70 ux_host_class_audio_control_get ... 71 ux_host_class_audio_control_value_set ... 72 ux_host_class_audio_streaming_sampling_set ... 73 ux_host_class_audio_streaming_sampling_get ... 74 ux_host_class_hid_client_register ... 76 ux_host_class_hid_report_callback_register ... 77ux_host_class_hid_periodic_report_start ... 78 ux_host_class_hid_periodic_report_stop ... 79 ux_host_class_hid_report_get ... 80 ux_host_class_hid_report_set ... 81 ux_host_class_asix_read ... 82 ux_host_class_asix_write ... 83 ux_host_class_cdc_acm_read ... 84 ux_host_class_cdc_acm _write ... 85 ux_host_class_cdc_acm_ioctl ... 86 ux_host_class_pima_session_open ... 88 ux_host_class_pima_session_close ... 89 ux_host_class_pima_storage_ids_get ... 90 ux_host_class_pima_storage_info_get ... 91 ux_host_class_pima_num_objects_get ... 92 ux_host_class_pima_object_handles_get ... 95 ux_host_class_pima_object_info_get ... 97 ux_host_class_pima_object_info_send ... 99 ux_host_class_pima_object_open ... 101 ux_host_class_pima_object_get ... 102 ux_host_class_pima_object_send ... 104 ux_host_class_pima_thumb_get ... 106 ux_host_class_pima_object_delete ... 108 ux_host_class_pima_object_close ... 109 ux_host_class_gser_read ... 110 ux_host_class_gser_write ... 111 ux_host_class_gser_ioctl ... 112 ux_host_class_gser_reception_start ... 114 ux_host_class_gser_reception_stop ... 115
第 6 章
USBX DPUMP クラスについて ... 116
USBX DPUMP ホストクラス ... 117 USBX DPUMP デバイスクラス ... 119第 7 章
ピクトブリッジの実装 ... 120
ピクトブリッジクライアントの実装 ... 121 ux_pictbridge_jobinfo_object_data_read ... 125 ピクトブリッジホストの実装 ... 126 ux_pictbridge_application_object_data_write ... 128第 8 章
USBX OTG ... 129
インデックス ... 132
本書について
本書では、Express Logic, Inc.の高性能 USB ファウンデーションソフトウェア USBX について包括的 に説明します。
本書は、組み込み式リアルタイムソフトウェアの開発者を対象にしています。開発者は、標準的なリ アルタイムオペレーティングシステムファンクション、USB 仕様、および C プログラミング言語に精通 していることとします。
USB 関連の技術的な情報については、http://www.USB.org/developers から USB 仕様書および USB クラス仕様書をダウンロードして参照してください。 本書の構成 第 1 章では、USB について紹介します。 第 2 章では、ThreadX アプリケーションに USBX をインストールして使用するための基本 手順を説明します。 第 3 章では、USBX の機能の概要と USB の基本事項を説明します。 第 4 章では、ホストモードの USBX へのアプリケーションのインタフェースについて詳述し ます。 第 5 章は、「USBX DPUMP クラスについて」と題しています。 第 6 章は、「USBX Pictbridge の実装」と題しています。 第 7 章は、「USBX OTG」と題しています。
第
1
章
USBX
の概要
USBX は、組み込みアプリケーション対応の本格的 USB スタックです。この章では USBX の概要を 紹介し、その用途と利点を説明します。
USBX の機能
USBX は、現行の USB Specification 1.1、2.0、および OTG をサポートします。スケーラブルに設計 してあるため、1 つだけのデバイスを接続する簡易 USB テクノロジから、複数のデバイスとカスケー ドハブを備えた複雑なテクノロジまで対応します。USB プロトコルで可能な制御転送、バルク転送、イ ンタラプト転送、アイソクロナス転送をすべて USBX でサポートします。 USBX はホスト側、デバイス側の両方をサポートします。いずれの側も、次の 3 つのレイヤで構成さ れます。 • 制御レイヤ • スタックレイヤ • クラスレイヤ USB 各相の関係は次のようになっています。 クラスドライバ クラスドライバ ホストスタック ホストコントローラ ドライバ ホストコントローラ デバイススタック ホストコントローラ ドライバ デバイスコントローラ ホスト 側 デバイ ス側
製品ハイライト
ThreadX プロセッサの完全なサポートロイヤルティなし 完全な ANSI C ソースコード リアルタイムパフォーマンス迅速なテクニカルサポート 複数のクラスサポート 複数のクラスインスタンス ThreadX、FileX、NetX とのクラス統合 複数コンフィギュレーション対応の USB デバイスのサポート USB 複合デバイスのサポート カスケードハブのサポート USB 電力管理のサポート USB OTG のサポート TraceX のトレースイベントのエクスポートUSBX の強力なサービス
複数ホストコントローラのサポート
USBX は、並列実行される複数の USB ホストコントローラをサポートできます。これにより、市販され ている USB 2.0 ホストコントローラの大半で採用している下位互換方式の USB 2.0 規格を USBX で サポートできます。USB ソフトウェアスケジューラ
ハードウェアリスト処理機能のない USB コントローラをサポートするには USB ソフトウェアスケジュー ラが必要ですが、そのスケジューラを USBX に内蔵しています。USBX のソフトウェアスケジューラは、 各 USB 転送を所定の頻度と優先度に応じて編成し、USB コントローラに命令して転送をそれぞれ実 行します。USB デバイスフレームワークの完全なサポート
複数コンフィギュレーション、複数インタフェース、複数代替設定などをともなう、最高度の USB デバ イスをサポートすることができます。使いやすい API
USBX は、最高の組み込み USB スタックを、わかりやすく簡単に使える形で提供します。USBX の API により、直感的かつ一貫したサービスが得られます。付属の USBX クラス API を使用すれば、 ユーザアプリケーション側で複雑な USB プロトコルを理解する必要がありません。
第
2
章
USBX
のインストール
ホストについて
コンピュータの種類
組み込み開発は通常、IBM-PC または Unix のホストコンピュータ上で実行されます。ホスト側でアプ リケーションをコンパイル、リンク、配置した後、ターゲットハードウェアにアプリケーションをダウン ロードして実行します。ダウンロード用インタフェース
ターゲットへのダウンロードは通常、RS-232 シリアルインタフェースを介して行いますが、パラレルイ ンタフェースや、USB、Ethernet を使用する例も増えています。対応するオプションに関する開発 ツールドキュメントを参照してください。デバッグツール
デバッグは一般に、プログラムイメージダウンロード用と同じリンクで実行されます。デバッガには、 BDM（Background Debug Monitor）や ICE（In-Circuit Emulator）ツールを介してターゲット上で実 行する小型のモニタプログラムを初め、各種があります。このうち、実際のターゲットハードウェアを 最も強力にデバッグできるのは、もちろん ICE ツールです。必要なハードディスク容量
USBX のソースコードは ASCII 形式で提供され、コンピュータのハードディスクに約 500KB の空き容 量が必要です。その他のホストシステム要件とオプションについては、付属の「readme_usbx.txt」 ファイルで確認してください。ターゲットについて
USBX は、ホストモードのターゲット上に 24KB～64KB の読み取り専用メモリ（ROM）が必要です。 必要なメモリ容量は、使用するコントローラ、および USBX にリンクする USB クラスにより異なります。 さらに、USBX グローバルデータ構造とグローバルメモリプール用には、ターゲットに 32KB のランダ ムアクセスメモリ（RAM）が必要になります。このメモリプールは、USB で実行するデバイス数、およ び USB コントローラの種類に応じて調整することも可能です。USBX デバイス側では、デバイスコン トローラの種類に応じて約 10～12K の ROM が必要です。RAM メモリの使用量は、デバイスでエミュ レートするクラスの種類により異なります。 さらに USBX では、マルチスレッド保護のために ThreadX の セマフォ、ミューテックス、スレッドを必 要とし、また USB バストポロジの監視のために I/O の中断と周期処理を必要とします。製品の配布 USBX パッケージには、標準とプレミアムの 2 種類があります。標準パッケージでは最小限のソース コードを備えているの対し、プレミアムパッケージには USBX ソースコードを一式完備しています。い ずれのパッケージも 1 枚の CD で出荷されます。 配布 CD の内容は、ターゲットプロセッサ、開発ツール、USBX パッケージにより異なります。以下は、 ほとんどの製品配布に共通する重要ファイルのリストです。 readme_usbx.txt USBX ポートに関するファイルで、ターゲットプロセッサ、開発ツールな どが含まれています。 ux_api.h すべてのシステム equate、データ構造、サービスプロトタイプを記述し た C ヘッダファイルです。 ux_port.h 開発ツール向けのデータ定義と構造をすべて記述した C ヘッダファイ ルです。 ux.lib USBX C ライブラリのバイナリバージョンです。標準パッケージで配布さ れます。。 demo_usbx.c 簡単な USBX デモを記述した C ファイルです。 ファイル名はすべて小文字で表します。これにより、コマンドを Unix 開発プラットフォームに簡単に変 換することができます。 USBX のインストールは簡単明快です。以下に示す全般的な方法は、ほぼすべてのインストールに 適 用 さ れ ま す 。 た だ し 、 実 際 の 開 発 ツ ー ル 環 境 に 応 じ た 変 更 点 に つ い て は 、 「readme_usbx_generic.txt」で確認してください。 ステップ 1 USBX 配布ディスクをバックアップし、安全な場所に保管しておきます。 ステップ 2 ホストハードドライブ上で以前に ThreadX をインストールしたのと同じディレクトリを 使用します。USBX 名はすべて一意となっているため、以前にインストールした USBX と干渉することはありません。 ステップ 3 tx_application_define またはその先頭付近に ux_system_initialize のコールを追 加します。tx_application_define.追加した場所で USBX リソースが初期化され ます。 ステップ 4 ux_host_stack_initialize へのコールを追加します。 ステップ 5 必要な USBX を初期化するためのコールを 1 つ以上追加します。 ステップ 6 システム内で使用可能なホストコントローラを初期化するためのコールを 1 つ以上 追加します。 ステップ 7 低レベルのハードウェア初期化と割り込みベクトルのルーティングを追加するため に、tx_low_level_initialize.c ファイルの修正が必要になる場合があります。ハード ウェアプラットフォームごとに異なるステップとなるため、ここでは説明しません。
ステップ 8 アプリケーションソースコードをコンパイルし、それを USBX と ThreadX のランタイ ムライブラリとリンクし（USB ストレージクラスや USB ネットワーククラスをコンパイ ルするときは FileX や Netx も必要になる場合があります）、また ux.a（または ux.lib） と tx.a（または tx.lib）にもリンクします。結果をターゲットにダウンロードすれば実行 できます。
コンフィギュレーションオプション
USBX ライブラリの構築用にいくつかのコンフィギュレーションオプションがあります。オプションはす べて ux_port.h に置かれています。 各コンフィギュレーションオプションについて、以下に詳述します。配布ディスクで提供される readme_usbx.txt ファイルに、その他の開発ツールオプションが記述されています。 UX_PERIODIC_RATE 個々のハードウェアプラットフォームにおける秒あたりのティック数です。デフォルトは 1000、すなわ ちミリ秒あたり 1 ティックです。 UX_MAX_CLASS_DRIVER USBX でロード可能なクラスの最大数です。クラスコンテナを表す値であり、1 クラスのインスタンス 数ではありません。例えば、USBX の実装にハブクラス、プリンタクラス、およびストレージクラスが必 要な場合、これらのクラスに属するデバイス数とは無関係に、UX_MAX_CLASS_DRIVER 値を 3 に 設定できます。 UX_MAX_HCD システムで使用可能なホストコントローラの数です。USB 1.1 対応には、この値は通常 1 に設定され、 USB 2.0 対応には 2 以上に設定できます。この値は、同時に実行する並列ホストコントローラの数を 表すものです。例えば、実行する OHCI のインスタンスが 2 つある場合、または EHCI コントローラ 1 つと OHCI コントローラが 1 つを実行する場合は、UX_MAX_HCD を 2 に設定します。 UX_MAX_DEVICES USB にアタッチ可能なデバイスの最大数を表します。1 つの USB に対する理論上の最大数は、通常 127 個です。メモリ節約のためにこの値を下げることが可能です。システム内の USB バス数とはか かわりなく、デバイスの合計数を表す値であるので留意してください。UX_MAX_ED コントローラプール内の ED の最大数を表します。この値は、1 つのコントローラにみに割り当てられ ます。複数のコントローラのインスタンスがある場合は、各々のコントローラにこの値が使用されま す。 UX_MAX_TD および UX_MAX_ISO_TD コントローラプール内の正規 TD とアイソクロナス TD の最大数を表します。この値は、1 つのコント ローラにみに割り当てられます。複数のコントローラのインスタンスがある場合は、各々のコントロー ラにこの値が使用されます。 UX_THREAD_STACK_SIZE USBX スレッドに関するスタックサイズ（単位: バイト）です。通常は、使用するプロセッサとホストコン トローラに応じて 1024～2048 バイトが可能です。 UX_THREAD_PRIORITY_ENUM バストポロジをモニタする USBX 列挙スレッドの ThreadX 優先度値です。 UX_THREAD_PRIORITY_CLASS 標準 USBX スレッドの ThreadX 優先度値です。 UX_THREAD_PRIORITY_KEYBOARD
USBX HID キーボードクラスの ThreadX 優先度値です。
UX_THREAD_PRIORITY_HCD ホストコントローラスレッドの ThreadX 優先度値です。 UX_NO_TIME_SLICE 1 を指定した場合、ThreadX ターゲットポートはタイムスライスを使用しません。 UX_MAX_HOST_LUN ホストストレージクラスドライバに表される SCSI 論理ユニットの最大数を表します
ソースコードツリー
USBX の各ファイルは、いくつかのディレクトリで提供されます。 USBX コア USBX デバイススタック USBX ホストスタック USBX デバイス コントローラ USBX ホスト コントローラ USBX ネットワーク USBX の例 ホストファイル Windows USBX OTG USBX デバイス クラス USBX ホストクラス各ファイルを名前で識別できるように、以下の表記法を採用しています。 ファイル接尾名 ファイルの説明 ux_host_stack USBX ホストスタックのコアファイル ux_host_class USBX ホストスタックのクラスファイル ux_hcd USBX ホストスタックのコントローラドライバファイル ux_device_stack USBX デバイススタックのコアファイル ux_device_class USBX デバイススタックのクラスファイル ux_dcd USBX デバイススタックのコントローラドライバファイル
ux_otg USBX OTG コントローラドライバ関連ファイル
ux_pictbridge USBX ピクトブリッジファイル ux_utility USBX ユーティリティファンクション demo_usbx USBX のデモファイル
USBX リソースの初期化
USBX は、自身のメモリマネージャを備えています。先に USBX にメモリを割り当てておかないと、 USBX のホスト側やデバイス側を初期化することができません。メモリキャッシュが可能なシステム にも、USBX メモリマネージャは対応します。 次のファンクションは、USBX メモリリソースを 128K の正規メモリで、かつキャッシュセーフメモリ用 プールを別途に設けずに初期化します。/* Initialize USBX Memory */
ux_system_initialize(memory_pointer,(128*1024),UX_NULL,0);
ux_system_initialize のプロトタイプは次の通りです。
UINT ux_system_initialize(VOID *regular_memory_pool_start, ULONG regular_memory_size, VOID *cache_safe_memory_pool_start, ULONG cache_safe_memory_size) 入力パラメータ: VOID *regular_memory_pool_start 正規メモリプールの先頭 ULONG regular_memory_size 正規メモリプールのサイズ VOID *cache_safe_memory_pool_start キャッシュセーフメモリプールの先頭 ULONG cache_safe_memory_size キャッシュセーフメモリプールのサイズ すべてのシステムでキャッシュセーフメモリの定義が必要なわけではありません。そのようなシステ ムでは、メモリポインタの初期化時に渡される値は UX_NULL に、プールの値は 0 にそれぞれ設定さ れます。その場合、USBX はキャッシュセーフメモリに代えて正規メモリプールを使用します。
正規メモリがキャッシュセーフではなく、またコントローラが DMA メモリを実行する必要がある場合 （OHCI、EHCI などのコントローラの場合）、キャッシュセーフメモリにメモリプールを定義することが 必要です。
USB ホストコントローラの定義
USBX がホストモードで動作するためには、USB ホストコントローラを 1 つ以上定義する必要があり ます。この定義は、アプリケーション初期化ファイルに記述します。下の例では、OHCI USB デバイ スコントローラを指しています。EHCI などその他のコントローラでは、そのコントローラの名前とファ ンクションエントリ定義を適宜変更しなければなりません。 次の行は、OHCI コントローラの定義を実行します。 ux_host_stack_hcd_register("ux_hcd_ohci", ux_hcd_ohci_initialize, 0xd0000, 0x0a); ux_host_stack_hcd_register のプロトタイプは次の通りです。 UINT_ux_host_stack_hcd_register(CHAR_PTR hcd_name,UINT (*hcd_initialize_function)(struct UX_HCD_STRUCT *), ULONG hcd_param1, ULONG hcd_param2); ux_host_stack_hcd_register ファンクションは次のパラメータを使用します。 hcd_name: コントローラ名のストリング hcd_initialize_function: コントローラの初期化ファンクション hcd_param1: 通常は、コントローラで使用する IO 値またはメモリ hcd_param2: 通常は、コントローラで使用する IRQ 前の例では次のようになります。
ux_hcd_ohci が OHCI コントローラの名前、ux_hcd_ohci_initialize が OHCI コントロー ラの初期化ルーチン、0xd0000 が OHCI コントローラレジスタがメモリ上で可視となって いるアドレス、そして 0x0a が OHCI で使用する IRQ です。
USBX では、現在、以下のコントローラをサポートしています。他のコントローラのサポートも予定さ れています。
ホストコントローラ名 商標およびプロセッサ（参考）
EHCI Generic 2.0 USB ホストコントローラ
OHCI Generic 1.1 USB ホストコントローラ
ISP1161 NXP 1.1 組み込み離散ホストコントローラ
ISP1362 NXP 2.0 組み込み離散ホストコントローラ
PIC32 Microchip 組み込み 1.1 ホストコントローラ
RX Renesas RX62 組み込みホストコントローラ
STM32 ST Micro STM32 F1/F2/F4 組み込みホストコントローラ MUSB Mentor ジェネリックホストコントローラ 以下は、1 つの OHCI コントローラといくつかのクラスを用いて、USBX をホストモードで初期化すると きの例です。 UINT status; /* Initialize USBX.*/ ux_system_initialize(memory_ptr, (128*1024),0,0);
/* The code below is required for installing the USBX host stack.*/ status = ux_host_stack_initialize(UX_NULL);
/* If status equals UX_SUCCESS, host stack has been initialized.*/ /* Register all the host classes for this USBX implementation.*/ status = ux_host_class_register("ux_host_class_hub",
ux_host_class_hub_entry); /* If status equals UX_SUCCESS, host class has been registered.*/
status = ux_host_class_register("ux_host_class_storage",
ux_host_class_storage_entry); /* If status equals UX_SUCCESS, host class has been registered.*/ status = ux_host_class_register("ux_host_class_printer",
ux_host_class_printer_entry); /* If status equals UX_SUCCESS, host class has been registered.*/ status = ux_host_class_register("ux_host_class_audio",
ux_host_class_audio_entry); /* If status equals UX_SUCCESS, host class has been registered.*/ /* Register all the USB host controllers available in this system.*/ status = ux_host_stack_hcd_register("ux_hcd_ohci",
ux_hcd_ohci_initialize, 0x300000, 0x0a);
/* If status equals UX_SUCCESS, USB host controllers have been registered.*/
ホストクラスの定義
1 つ以上のホストクラスを USBX で定義する必要があります。USB スタックで USB デバイスをコン フィギュレーションした後に USB デバイスを駆動するために USB クラスが必要になります。USB クラ スは USB デバイスに特化しています。
USB デバイス記述子に含まれるインタフェース数に応じ、1 つの USB デバイスを駆動するために 1 つまたは複数のクラスが必要になることがあります。 以下は、HUB クラスの登録例です。 status = ux_host_stack_class_register("ux_host_class_hub", ux_host_class_hub_entry); ux_host_class_register のプロトタイプは次の通りです。
UINT ux_host_staack_class_register(CHAR_PTR class_name, UINT (*class_entry_address)
(struct UX_HOST_CLASS_COMMAND_STRUCT *))
class_name はクラス名、class_entry_address はクラスのエンドポイントです。 HUB クラスの初期化例において: ux_host_class_hub はハブの名前です。
トラブルシューティング
USBX には、デモファイルとシミュレーション環境が付属しています。最初に、ターゲットハードウェア または特定のデモプラットフォームでデモプラットフォームを実行してみるのがよいでしょう。 デモシステムが機能しない場合、以下の方法で問題を絞り込んでください。USBX バージョン ID
USBX の現在のバージョンは、実行時にユーザからもアプリケーションソフトウェアからも確認できま す。 プログラマは、usbx.txt ファイルを調べて USB バージョンを取得できます。このファイルには、対応す るポートのバージョン履歴も記載されています。アプリケーションソフトウェアでは、ux_port.h に定義 されているグローバルストリング_ux_version_id を調べて USBX バージョンを取得できます。第
3
章
USBX
ホストスタックのファンクション
コンポーネント
この章では、USBX の高性能埋め込み USB ホストスタックについて、ファンクションの観点から説明 します。実行概要
USBX は、次のコンポーネントから構成されます。 初期化 アプリケーションインタフェースコール ルートハブ ハブクラス ホストクラス USB ホストスタック ホストコントローラ USBX ホストスタックを下の図に示します。 キーボード クライアント ライアント マウスク リモート コントロール クライアント ハブクラス アイソクロナス クラス 非同期クラス HID クラス USB スタック OHCI EHCI ソフトウェア スケジューラ コントローラドライバ初期化
USBX をアクティブ化するには、ファンクション ux_system_initialize をコールする必要があります。 このファンクションは USBX のメモリリソースを初期化します。 USBX ホスト機能をアクティブ化するには、ファンクション ux_host_stack_initialize をコールする必 要があります。ThreadX スレッド、ミューテックス、セマフォなど、USBX ホストスタックで使用するすべ てのリソースがこのファンクションで初期化されます。 1 つ以上の USB ホストコントローラと 1 つ以上の USB クラスをアクティブ化するのは、アプリケーショ ン初期化での処理になります。スタックにクラスが登録され、ホストコントローラ初期化ファンクション がコールされたら、バスがアクティブになり、デバイス発見が開始できます。ホストコントローラのルー トハブが、アタッチされているデバイスを検出した場合、USB トポロジを担当する USB 列挙スレッド がウェイクアップし、デバイスの列挙処理に進みます。 ルートハブおよび下流ハブの性質上、ホストコントローラ初期化ファンクションが返ったときに、アタッ チされているすべての USB デバイスがまだ完全にコンフィギュレーションされていない可能性があり ます。USB ハブの列挙に際し、特にルートハブと USB デバイスの間に 1 つ以上のハブがある場合、 すべてが列挙されるまでに数秒かかることがあります。アプリケーションインタフェースコール
USBX の API には、次の 2 つのレベルがあります。 USB ホストスタック API USB ホストクラス API通常、USBX アプリケーションではどの USB ホストスタック API もコールする必要がありません。ほと んどのアプリケーションは、USB クラス API にのみアクセスします。
USB ホストスタック API
ホストスタック API は、USBX コンポーネント（ホストクラスとホストコントローラ）の登録、デバイスのコ ンフィギュレーション、および使用可能なデバイスエンドポイントの転送要求を担当します。
USB ホストクラス API
クラス API は、USB クラスごとに特化しています。USB クラス用の一般的な API のほとんどは、デバ イスのオープン／クローズ、デバイスとの読み書きなどのサービスを提供します。
ルートハブ
ホストコントローラの各インスタンスには、1 つ以上の USB ルートハブがあります。ルートハブの数は、 コントローラの性質によって決まるか、またはコントローラから特定のレジスタを読み出すことで取得 できます。ハブクラス
ハブクラスは、USB ハブの駆動を担当します。USB ハブは、スタンドアロンハブのほか、キーボード、 モニタなど複合デバイスの一部とすることも可能です。ハブには、自己電力形とバス電力形がありま す。バス電力ハブでは、最大 4 つまでの下流ポートを搭載でき、また使用電力が 100mA 未満の自 己電力またはバス電力のデバイスのみが接続可能です。各ハブのカスケード化が可能です。最大 5 つのハブを相互に接続できます。USB ホストスタック
USB ホストスタックは、USBX の中核部分です。次の 3 つの主要機能を持ちます。 • USB のトポロジの管理 • 1 つ以上のクラスへの USB デバイスのバインド • デバイス記述子問い合わせと USB 転送を実行するための、API をクラスに提供トポロジマネージャ
新しいデバイスが接続されるまたはデバイスの接続が外されると、USB スタックトポロジスレッドが ウェイクアップされます。ルートハブでも正規ハブでも、デバイスの接続を受け付けることができます。 USB にデバイスが接続されると、トポロジマネージャがデバイス記述子を取得します。この記述子に は、そのデバイスで可能なコンフィギュレーションの数が示されています。ほとんどのデバイスは、1 つのコンフィギュレーションのみを備えています。接続先ポートでの使用可能電力に従って、異なる 動作が可能なデバイスもあります。そのようなデバイスには、使用可能電力に応じて複数のコンフィ ギュレーションがあり、選択できるようにしてあります。トポロジマネージャによりコンフィギュレーショ ンされたデバイスには、コンフィギュレーション記述子に指定されている電力が供給できるようになり ます。USB クラスのバインド
デバイスがコンフィギュレーションされたらトポロジマネージャは、クラスマネージャがデバイスインタ フェース記述子を見ながらデバイス発見を続行するようにさせます。各デバイスには 1 つ以上のイン タフェース記述子を持つことができます。 インタフェースとは、デバイスに含まれるファンクションです。例えば、USB スピーカには、オーディオ ストリーミング用、オーディオコントロール用、各種スピーカボタンの管理用のインタフェースが各 1 個、 合計 3 個のインタフェースがあります。クラスマネージャには、デバイスインタフェースを 1 つ以上のクラスに結合するメカニズムが 2 つあり ます。すなわち、インタフェース記述子に含まれている PID/VID（製品 ID とベンダ ID）の組み合わせ を使用するメカニズムと、クラス／サブクラス／プロトコルの組合せを使用するメカニズムがありま す。 PID/VID の組み合わせは、ジェネリッククラスによる駆動ができないインタフェースに対して有効です。 クラス／サブクラス／プロトコルの組合せは、USB-IF 認定のクラス（プリンタ、ハブ、ストレージ、オー ディオ、HID など）に属するインタフェースで使用されます。 クラスマネージャには、USBX の初期化で登録されたクラスのリストがあります。クラスマネージャは、 クラスを 1 つずつコールしていき、そのデバイスのインタフェースの管理をいずれかのクラスが引き 受けるようになるまでコールを続けます。1 つのクラスでは 1 つのインタフェースのみを管理できます。 USB オーディオスピーカの例では、インタフェースの各々に対してクラスマネージャがすべてのクラ スをコールします。 あるクラスがインタフェースを引き受けたら、そのクラスの新しいインスタンスが作成されます。次にク ラスマネージャは、そのインタフェースのデフォルトの代替設定を探します。各デバイスでは、個々の インタフェースごとに 1 つ以上の代替設定を設けることができます。クラスで他の代替設定への変更 が決定されるまでは、デフォルトの代替設定 0 が使用されます。 デフォルトの代替設定時には、クラスマネージャは代替設定に含まれるすべてのエンドポイントをマ ウントします。各エンドポイントのマウントに成功すると、クラスマネージャは最後にそのクラスに返り、 インタフェースの初期化が完成します。
USBX API
USB スタックから、一定数の API がエクスポートされます。これらは、USB クラスがデバイスでの問 い合わせおよび特定のエンドポイントでの USB 転送を実行するための API です。これら API につい ては、リフェレンスマニュアルに詳述されています。
ホストコントローラ
ホストコントローラドライバは、特定の種類の USB コントローラを駆動する任にあたります。USB ホス トコントローラは複数のコントローラを内蔵できます。例えば、ある種のインテル PC チップセットは 2 つの UHCI コントローラを搭載しています。また、一部の USB 2.0 コントローラには、EHCI コントロー ラのインスタンス 1 つに加え、OHCI コントローラのインスタンスを複数搭載しているものがあります。 ホストコントローラでは、同一のコントローラのみの複数のインスタンスを管理します。ほとんどの USB 2.0 ホストコントローラを駆動するためには、USBX の初期化時に OCHI コントローラと EHCI コ ントローラの両方を初期化することが必要になります。 ホストコントローラは、以下のものを管理の対象とします。 ルートハブ Power Management Endpoints Transfers
ルートハブ
ルートハブ管理では、各コントローラポートに電源を投入し、挿入されているデバイスがあるかどうか を判定します。この機能を USBX ジェネリックルートハブが使用し、コントローラの下流ポートに問い 合わせを行います。電力管理
電力管理処理は、中断／再開信号を扱うための機能です。ギャングモードにしてコントローラのすべ ての下流ポートに同時に影響するようにするか、または（コントローラ側で対応している場合は）各 ポートに対して個別に使用します。エンドポイント
エンドポイント管理では、コントローラへの物理エンドポイントを作成または破壊することができます。 物理エンドポイントとはメモリエンティティのことで、マスターDMA をサポートするコントローラで解析 される場合と、コントローラに書き込まれている場合があります。物理エンドポイントには、コントロー ラにより実行されるトランザクション情報が含まれています。転送
転送管理とは、作成した各エンドポイントでクラスがトランザクションを実行するためのものです。各 論理エンドポイントには、USB 転送要求用の TRANSFER REQUESTというコンポーネントが含まれ ています。TRANSFER REQUEST は、トランザクションを記述するためにスタックで使用されます。 この TRANSFER REQUEST がスタックとコントローラに渡され、コントローラではその能力に応じて いくつかのサブトランザクションに分割することができます。USB デバイスのフレームワーク
USB デバイスは、記述子のツリーで表されます。記述子は次の 6 種類に大別されます。 デバイス記述子 コンフィギュレーション記述子 インタフェース記述子 エンドポイント記述子 ストリング記述子 ファンクショナル記述子 USB デバイスは、ごく簡潔に記述することが可能で、その場合は次のようになります。 上の図では、デバイスに含まれるコンフィギュレーションは 1 つだけです。このコンフィギュレーション に 1 つのインタフェースがアタッチされています。すなわち、このデバイスではファンクションが 1 つだ け、エンドポイントも 1 つだけです。デバイス記述子にストリング記述子をアタッチして、デバイスの識 別を可視化しています。 デバイス 記述子 ストリング 記述子 コンフィギュレーション 記述子 インタフェース 記述子 エンドポイント 記述子逆に、もっと複雑なデバイスも可能で、その場合は次のようになります。 上の図では、デバイス記述子にコンフィギュレーション記述子が 2 つアタッチされています。このデバ イスでは、電力モードが 2 つある場合や、標準クラスや各社独自のクラスで駆動される場合などがあ ります。 最初のコンフィギュレーションには 2 つのインタフェースがアタッチされている、すなわち 2 つの論理 ファンクションを持っています。最初のファンクションには、エンドポイント記述子が 3 つ、ファンクショ ナル記述子が 1 つあります。ファンクショナル記述子は、例えばインタフェースの駆動を担うクラスが 使用し、このインタフェースに関してジェネリック記述子には含まれていないような追加情報を取得し たりします。 デバイス記述子 ストリング記述子 コンフィギュレーション 記述子 コンフィギュレーション 記述子 インタフェース 記述子 インタフェース 記述子 インタフェース 記述子 エンドポイント 記述子 エンドポイント 記述子 エンドポイント 記述子 エンドポイント 記述子 エンドポイント 記述子 エンドポイント 記述子 エンドポイント 記述子 ファンクショナル 記述子 ファンクショナル 記述子 ファンクショナル 記述子
デバイス記述子
各 USB デバイスには、デバイス記述子が 1 つあります。この記述子には、デバイス識別子、サポー トしているコンフィギュレーションの数、およびデバイスのコンフィギュレーションに使用するデフォルト の制御エンドポイントの特性が記述されます。 オフ セット フィールド サイズ 値 説明 0 BLength 1 数値 この記述子のサイズ（単位、バイト） 1 bDescriptorType 1 定数 デバイス記述子の型 2 bcdUSB 2 BCD USB 仕様リリース番号（2 進化 10 進数） 例例: 2.10 は 0x210 と等しい。このフィールドには、デバ イスとその記述子が準拠する USB 仕様のリリース番号 を示します。 4 bDeviceClass 1 クラス クラスコード（USB-IF により割り当てられる）。 このフィールドを 0 にリセットすると、コンフィギュレーショ ン内の各インタフェースが自身のクラス情報を指定し、 それぞれのインタフェースが独立して動作します。 このフィールドを 1～0xFE の値に設定すると、デバイス はインタフェースごとに異なるクラス仕様をサポートする ことになり、各インタフェースは独立して動作しない場合 があります。この値は、インタフェースの集合に使用され るクラス定義を特定します。 このフィールドを 0xFF に設定すると、ベンダ固有のデバ イスクラスになります。 5 bDeviceSubClass 1 サブクラス サブクラスコード（USB-IF により割り当てられる）。 これらのコードは bDeviceClass フィールドの値に修飾さ れます。bDeviceClass フィールドが 0 にリセットされた 場合は、このフィールドも 0 にリセットする必要がありま す。bDeviceClass フィールドが 0xFF に設定されない場 合、すべての値が USB による割り当て用に予約されま す。 6 bDeviceProtocol 1 プロトコル プロトコルコード（USB-IF により割り当てられる）。 こ れ ら の コ ー ド は bDeviceClass フ ィ ー ル ド と bDeviceSubClass フィールドの値に修飾されます。イン タフェースベースではなくクラスベースのクラス固有プロ トコルをサポートするデバイスでは、デバイスが使用す るプロトコルを、デバイスクラスの仕様の定義に従ってこ のコードで識別します。このフィールドを 0 にリセットする と、デバイスはクラス固有プロトコルをデバイスベースで 使用しません。 ただし、インタフェースベースでクラス固有プロトコルを 使用することはできます。 このフィールドを 0xFF に設定すると、デバイスはベンダ 固有プロトコルをデバイスベースで使用します。 7 bMaxPacketSize0 1 数値 エンドポイント 0 の最大パケットサイズ（バイトサイズ 8、 16、32、または 64 のみが有効） 8 idVendor 2 ID ベンダ ID（USB-IF により割り当てられる）10 idProduct 2 ID 製品 ID（メーカーにより割り当てられる） 12 bcdDevice 2 BCD デバイスリリース番号（2 進化 10 進数） 14 iManufacturer 1 インデックス メーカーを記述するストリング記述子のインデックス 15 iProduct 1 インデックス 製品を記述するストリング記述子のインデックス 16 iSerialNumber 1 インデックス デバイスのシリアル番号を記述するストリング記述子の インデックス 17 bNumConfiguration s 1 数値 可能なコンフィギュレーションの数 USBX では、USB デバイス記述子を次のように定義します。
typedef struct UX_DEVICE_DESCRIPTOR_STRUCT { UINT bLength; UINT bDescriptorType; USHORT bcdUSB; UINT bDeviceClass; UINT bDeviceSubClass; UINT bDeviceProtocol; UINT bMaxPacketSize0; USHORT idVendor; USHORT idProduct; USHORT bcdDevice; UINT iManufacturer; UINT iProduct; UINT iSerialNumber; UINT bNumConfigurations; } UX_DEVICE_DESCRIPTOR; USB デバイス記述子は、以下のデバイスコンテナの一部となっています。
typedef struct UX_DEVICE_STRUCT { ULONG ux_device_handle; ULONG ux_device_type; ULONG ux_device_state; ULONG ux_device_address; ULONG ux_device_speed; ULONG ux_device_port_location; ULONG ux_device_max_power; ULONG ux_device_power_source; UINT ux_device_current_configuration; TX_SEMAPHORE ux_device_protection_semaphore; struct UX_DEVICE_STRUCT *ux_device_parent; struct UX_HOST_CLASS_STRUCT *ux_device_class; VOID *ux_device_class_instance; struct UX_HCD_STRUCT *ux_device_hcd; struct UX_CONFIGURATION_STRUCT *ux_device_first_configuration; struct UX_DEVICE_STRUCT *ux_device_next_device; struct UX_DEVICE_DESCRIPTOR_STRUCT ux_device_descriptor;
struct UX_ENDPOINT_STRUCT ux_device_control_endpoint; struct UX_HUB_TT_STRUCT ux_device_hub_tt[UX_MAX_TT]; } UX_DEVICE; 変数名 変数の説明 ux_device_handle デバイスのハンドル。通常は、デバイスのこの構造のイン スタンスのアドレスです。 ux_device_type 廃止された値。不使用。 ux_device_state デバイスステート。次のいずれかの値を設定できます。 UX_DEVICE_RESET 0 UX_DEVICE_ATTACHED 1 UX_DEVICE_ADDRESSED 2 UX_DEVICE_CONFIGURED 3 UX_DEVICE_SUSPENDED 4 UX_DEVICE_RESUMED 5 UX_DEVICE_SELF_POWERED_STATE 6 UX_DEVICE_SELF_POWERED_STATE 7 UX_DEVICE_REMOTE_WAKEUP 8 UX_DEVICE_BUS_RESET_COMPLETED 9 UX_DEVICE_REMOVED 10 UX_DEVICE_FORCE_DISCONNECT 11 ux_device_address SET_ADDRESS コマンドが受け付けられた後のデバイス のアドレス（1～127）。 ux_device_speed デバイスの速度。 UX_LOW_SPEED_DEVICE 0 UX_FULL_SPEED_DEVICE 1 UX_HIGH_SPEED_DEVICE 2 ux_device_port_location 親デバイス（ルートハブまたはハブ）のポートのインデック ス。 ux_device_max_power 選択されたコンフィギュレーションにおいてデバイスに取り 込める最大電力（単位、mA）。 ux_device_power_source 次の 2 つのいずれかの値が可能です。 UX_DEVICE_BUS_POWERED 1 UX_DEVICE_SELF_POWERED 2 ux_device_current_configuration このデバイスで現在使用しているコンフィギュレーションの インデックス。 ux_device_parent このデバイスの親のデバイスコンテナポインタ。ポインタが NULL なら、コントローラのルートハブが親です。
ux_device_class このデバイスを所有するクラス型へのポインタ。 ux_device_class_instance このデバイスを所有するクラスのインスタンスへのポイン タ。 ux_device_hcd このデバイスがアタッチされる USB ホストコントローライン スタンス。 ux_device_first_configuration このデバイスの 1 番目のコンフィギュレーションコンテナへ のポインタ。 ux_device_next_device USBX により検出されるいずれかのバスにあるデバイス のうち、デバイスリストに含まれる次のデバイスへのポイ ンタ。
ux_device_descriptor USB device descriptor.
ux_device_control_endpoint このデバイスで使用するデフォルトの制御エンドポイントの 記述子。 ux_device_hub_tt デバイスのハブ TT の配列。
コンフィギュレーション記述子
コンフィギュレーション記述子には、特定のデバイスコンフィギュレーションに関する情報を記述しま す。USB デバイスには、1 つ以上のコンフィギュレーション記述子を含めることができます。デバイス 記述子の bNumConfigurations フィールドに、コンフィギュレーション記述子の数が示されます。コン フィギュレーション記述子の bConfigurationValue フィールドの値は、それが Set Configuration 要求 へのパラメータとして使用された場合、その値に対応するコンフィギュレーションをデバイスが取るよ うになります。 コンフィギュレーション記述子には、コンフィギュレーションで提供されるインタフェースの数を記述し ます。各インタフェースは、デバイス内での論理ファンクションを表すもので、それぞれ独立して動作 することが可能です。例えば USB オーディオスピーカでは、オーディオストリーミングインタフェース、 オーディオコントロールインタフェース、各種スピーカボタンの管理用の HIDインタフェースが各 1 個、 合計 3 個のインタフェースを設けることができます。 ホストがコンフィギュレーション記述子に対して GET_DESCRIPTOR 要求を発行すると、関連するイ ンタフェース記述子とエンドポイント記述子がすべて返されます。オフセット フィールド サイズ 値 説明 0 bLength 1 数値 この記述子のサイズ（単位、バイト） 1 bDescriptorType 1 定数 コンフィギュレーション 2 wTotalLength 2 数値 このコンフィギュレーションに対して返される データの合計長さ。このコンフィギュレーション に対して返されるすべての記述子（コンフィギュ レーション、インタフェース、エンドポイント、お よびクラス固有またはベンダ固有）を組合わせ た長さが含まれます。 4 bNumInterfaces 1 数値 このコンフィギュレーションでサポートされるイ ンタフェースの合計数。 5 bConfigurationValue 1 数値 このコンフィギュレーションを選択するために Set Configuration の引数として使用する値。 6 iConfiguration 1 インデックス このコンフィギュレーションを記述するストリン グ記述子のインデックス。 7 bMAttributes 1 ビットマップ コンフィギュレーション特性 D7 バス電力 D6 自己電力 D5 リモートウェイクアップ D4..0 予約済み（0 にリセット） バスからの電力およびローカル電源を使用す るデバイスコンフィギュレーションでは、D7 と D6 の両方をセットします。実行時の実際の電 源は、Get Status デバイス要求を使用して決 定することも可能です。 デバイスコンフィギュレーションがリモートウェイ クアップをサポートする場合は、D5 を 1 に設定 します。 8 MaxPower 1 mA デバイスが完全に機能するときに、このコン フィギュレーションにおいてバスから供給される 電力に対する USB デバイスの最大消費電力。 2mA 単位で表します（例: 50 = 100mA）。 注: コンフィギュレーションがバス電力か自己電 力かは、デバイスコンフィギュレーションで報告 します。 デバイスは現在自己電力で動作しているかど うかは、デバイスステータスで報告します。デ バイスの外部電源から接続が切断したときは、 デバイスがデバイスステータスを更新し、自己 電力ではなくなっていることを示します。
USBX では USB コンフィギュレーション記述子を次のように定義します。
typedef struct UX_CONFIGURATION_DESCRIPTOR_STRUCT { UINT bLength; UINT bDescriptorType; USHORT wTotalLength; UINT bNumInterfaces; UINT bConfigurationValue; UINT iConfiguration; UINT bmAttributes; UINT MaxPower; } UX_CONFIGURATION_DESCRIPTOR; USB コンフィギュレーション記述子は、以下のコンフィギュレーションコンテナの一部となっています。
typedef struct UX_CONFIGURATION_STRUCT {
ULONG ux_configuration_handle;
ULONG ux_configuration_state; struct UX_CONFIGURATION_DESCRIPTOR_STRUCT
ux_configuration_descriptor;
struct UX_INTERFACE_STRUCT *ux_configuration_first_interface; struct UX_CONFIGURATION_STRUCT
*ux_configuration_next_configuration; struct UX_DEVICE_STRUCT *ux_configuration_device;
} UX_CONFIGURATION;
変数名 変数の説明
ux_configuration_handle コンフィギュレーションのハンドル。通常は、コンフィギュ レーションのこの構造のインスタンスのアドレスです。 ux_configuration_state コンフィギュレーションのステート
ux_configuration_descriptor USB device descriptor.
ux_configuration_first_interface このコンフィギュレーションの 1 番目のインタフェースへの ポインタ ux_configuration_next_configuration 同じデバイスの次のコンフィギュレーションへのポインタ ux_configuration_device このコンフィギュレーションのデバイス所有者へのポインタ
インタフェース記述子
インタフェース記述子には、コンフィギュレーション内の特定のインタフェースについて記述します。イ ンタフェースとは、USB デバイス内の論理ファンクションです。コンフィギュレーションには 1 つ以上の インタフェースを備えています。各インタフェースには、コンフィギュレーションに含まれるエンドポイン トの一意のセットを記述する、エンドポイント記述子が 0 個以上含まれます。2 つ以上のインタフェー ス を サ ポ ー ト す る コ ン フ ィ ギ ュ レ ー シ ョ ン で は 、 指 定 さ れ た コ ン フ ィ ギ ュ レ ー シ ョ ン に つ い て GET_DESCRIPTOR 要求から返されるデータに含まれるインタフェース記述子に、各インタフェース のエンドポイント記述子が従います。イ ン タ フ ェ ー ス 記 述 子 は 、 必 ず コ ン フ ィ ギ ュ レ ー シ ョ ン 記 述 子 の 一 部 と し て 返 さ れ ま す 。 GET_DESCRIPTOR 要求からインタフェース記述子に直接アクセスすることはできません。 デバイスをコンフィギュレーションした後にエンドポイントやその特性を変更できるように、代替設定を インタフェースに含めることができます。インタフェースのデフォルト設定では、常に代替設定が 0 で す。現在の代替設定をクラスから変更することで、インタフェースの挙動および関連するエンドポイン ト の 特 性 を 変 更 す る こ と が で き ま す 。 代 替 設 定 の 選 択 や デ フ ォ ル ト 設 定 へ の 復 帰 に は 、 SET_INTERFACE 要求を使用します。 代替設定を使用することで、他のインタフェースを作動させたままでデバイスのコンフィギュレーショ ンを一部変更することができます。1 つまたは複数のインタフェースに対して代替設定を備えている コンフィギュレーションでは、別のインタフェース記述子とその関連エンドポイントが代替設定ごとに 含まれます。 2 つの代替設定を持つ 1 つのインタフェースを記述したデバイスコンフィギュレーションの場合、この コンフィギュレーションに GET_DESCRIPTOR 要求を発行すると、コンフィギュレーション記述子が 返され、 次に bInterfaceNumber フィールドと bAlternateSetting フィールドが共に 0 に設定されたイ ンタフェース記述子が返され、その次にその設定のエンドポイント記述子が返されます。その後に、 もう 1 つのインタフェース記述子およびそれに関連するエンドポイント記述子が返されてきます。2 番 目のインタフェース記述子では、bInterfaceNumber フィールドは 0 に設定されていますが、 bAlternateSetting フィールドは 1 に設定されています。つまり、この代替設定は 1 番目のインタ フェースに属するものです。 関連するエンドポイントを持たないインタフェースもありますが、その場合は、デフォルトの制御エンド ポイントのみが有効なインターフェイスとなっています。 代替設定は主に、インタフェースに関連する周期的エンドポイントへの要求帯域幅を変更するために 使用されます。例えば USB スピーカのストリーミングインタフェースの場合、1 番目の代替設定には、 アイソクロナスエンドポイントでの帯域幅需要として 0 を設定します。その他の代替設定では、オー ディオストリーミング周波数に応じて異なる帯域幅要件が選択できます。 インタフェースの USB 記述子は次のようになっています。 オフ セット フィールド サイズ 値 記述子 0 bLength 1 数値 この記述子のサイズ（単位、バイト） 1 bDescriptorType 1 定数 インタフェース記述子の型 2 bInterfaceNumber 1 数値 インタフェースの番号。このコンフィギュレーションで サポートされる並列インタフェースの配列内のイン デックスを示す、ゼロベースの値。 3 bAltenateSetting 1 数値 前のフィールドで示したインタフェースに対する代替 設定を選択するための値。 4 bNumEndpoints 1 数値 この値を 0 に設定すると、このインタフェースはエ ンドポイント 0 のみを使用します。
5 bInterfaceClass 1 クラス クラスコード（USB により割り当てられる）。 この値を 0 にリセットすると、インタフェースは USB 指定のどのデバイスクラスにも属さなく なります。 このフィールドを 0xFF に設定すると、インタ フェースクラスはベンダ固有になります。 その他の値はすべて、USB による割り当て 用に予約されています。 6 bInterfaceSubClas s 1 サブクラス サブクラスコード（USB により割り当てられ る）。 これらのコードは bInterfaceClass フィールド の値に修飾されます。bInterfaceClass フィー ルドが 0 にリセットされた場合は、このフィー ルドも 0 にリセットする必要があります。 bInterfaceClass フィールドが 0xFF に設定さ れない場合、すべての値が USB による割り 当て用に予約されます。 7 bInterfaceProtocol 1 プロトコル プロトコルコード（USB により割り当てられ る）。これらのコードは bInterfaceClass フィー ルドと bInterfaceSubClass フィールドの値に 修飾されます。クラス固有要求をインタフェー スでサポートする場合、デバイスクラスの仕 様に従ってデバイスが使用するプロトコル を、このコードで特定します。 このフィールドを 0 にリセットすると、デバイス はこのインタフェースにクラス固有プロトコル を使用しません。このフィールドを 0xFF に設 定すると、デバイスはこのインタフェースにベ ンダ固有プロトコルを使用します。 8 iInterface 1 インデックス このインタフェースを記述するストリング記述 子のインデックス。 USBX では、USB インタフェース記述子を次のように定義します。
typedef struct UX_INTERFACE_DESCRIPTOR_STRUCT { UINT bLength; UINT bDescriptorType; UINT bInterfaceNumber; UINT bAlternateSetting; UINT bNumEndpoints; UINT bInterfaceClass; UINT bInterfaceSubClass; UINT bInterfaceProtocol; UINT iInterface; } UX_INTERFACE_DESCRIPTOR;
USB インタフェース記述子は、以下のインタフェースコンテナの一部となっています。
typedef struct UX_INTERFACE_STRUCT {
ULONG ux_interface_handle; ULONG ux_interface_state;
ULONG ux_interface_current_alternate_setting; struct UX_INTERFACE_DESCRIPTOR_STRUCT ux_interface_descriptor;
struct UX_HOST_CLASS_STRUCT *ux_interface_class;
VOID *ux_interface_class_instance; struct UX_ENDPOINT_STRUCT *ux_interface_first_endpoint; struct UX_INTERFACE_STRUCT *ux_interface_next_interface; struct UX_CONFIGURATION_STRUCT *ux_interface_configuration; } UX_INTERFACE; 変数名 変数の説明 ux_interface_handle インタフェースのハンドル。通常は、インタフェースのこの構造 のインスタンスのアドレスです。 ux_interface_state インタフェースのステート ux_interface_descriptor USB インタフェース記述子 ux_interface_class このインタフェースを所有するクラス型へのポインタ ux_interface_class_instance このインタフェースを所有するクラスのインスタンスへのポイン タ ux_interface_first_endpoint このインタフェースで登録される 1 番目のエンドポイントへのポ インタ ux_interface_next_interface このコンフィギュレーションに関連する次のインタフェースへの ポインタ ux_interface_configuration このインタフェースのコンフィギュレーション所有者へのポインタ
エンドポイント記述子
インタフェースに関連するエンドポイントには、それぞれ自身のエンドポイント記述子があります。こ の記述子には、各エンドポイントに関し、その帯域幅要件、関連する最大ペイロード、周期性、およ び方向を、それぞれホストスタックで決定するのに必要な情報を記述します。エンドポイント記述子は 常に、コンフィギュレーションに対する GET_DESCRIPTOR コマンドによって返されます。 デバイス記述子に関連するデフォルトの制御エンドポイントは、インタフェースに関連するエンドポイ ントの一部とはカウントされないため、この記述子では返されません。 インタフェースの代替設定の切り替えをホストソフトウェアが要求するときは、関連するすべてのエン ドポイントとその USB リソースが新しい代替設定に従って修正されます。 デフォルトの制御エンドポイントを除き、エンドポイントをインタフェース間で共有することはできませ ん。オフセット フィールド サイズ 値 説明 0 bLength 1 数値 この記述子のサイズ（単位、バイト） 1 bDescriptorType 1 定数 エンドポイント記述子の型 2 bEndpointAddress 1 エンドポイント この記述子に記述される USB デバイス上のエンドポイ ントのアドレス。アドレスは次のようにエンコードされま す。 ビット 3～0: エンドポイント番号 ビット 6～4:予約（0 にリセット） ビット 7: 方向（制御エンドポイントの場合は無視） 0 = OUT エンドポイント 1 = IN エンドポイント 3 bmAttributes 1 ビットマップ このフィールドには、bConfigurationValue を用いてエ ンドポイントをコンフィギュレーションするときの、エンド ポイントの属性を記述します。 ビット 1～0: 転送の種類 00 = 制御 01 = アイソクロナス 10 = バルク 11 = インタラプト アイソクロナスエンドポイントでない場合は、ビット 5～ 2 は予約されていて、0 に設定する必要があります。ア イソクロナスの場合は、次のように定義されます。 ビット 3～2:同期の種類 00 = 同期なし 01 = 非同期 10 = 適応 11 = 同期 ビット 5～4:使用法の種類 00 = データエンドポイント 01 = フィードバックエンドポイント 10 = インプリシット・フィードバックデータエンドポイント 4 wMaxPacketSize 2 数値 このコンフィギュレーションを選択したときにこのエンド ポイントで送受信可能な最大パケットサイズ。 アイソクロナスエンドポイントの場合は、（マイクロ）フ レームあたりのデータペイロードに必要となるバス時 間を、この値でスケジュールに予約します。パイプで実 際に使用される帯域幅（継続ベース）は、予約した帯 域幅より少ない場合があります。実際に使用した帯域 幅は、デバイスから通常の非 USB 定義のメカニズム を介して必要に応じて報告されます。 すべてのエンドポイントについて、ビット 10～0 で最大 パケットサイズを指定します。
高速アイソクロナスおよびインタラプトのエンド ポイントの場合は: ビット 12～11 では、マイクロフレームあたりの 追加トランザクション機会数を指定します。 00 = なし（1 トランザクション／マイクロフレー ム）
01 = 1 additional (2 per microframe) 10 = 2 つ追加（3／マイクロフレーム） 11 = 予約 ビット 15～13 は予約済みで、0 に設定する必要があり ます。 6 bInterval 1 数値 データ転送用にエンドポイントをポーリングする間 隔数値。 デバイスの動作速度に応じてフレーム数またはマ イクロフレーム数で表します（1 ミリ秒または 125 マ イクロ秒単位）。 全速／高速アイソクロナスエンドポイントでは、この 値を 1～16 の範囲に設定する必要があります。 bInterva 値は、2 x bInterval - 1 の値の指数として 使用されます。例えば、bInterval を 4 にすると、8 (24-1)の周期になります。 全速／低速インタラプトエンドポイントでは、この フィールドの値は 1～255 が可能です。 高速インタラプトエンドポイントでは、bInterva 値 は、2×bInterval - 1 の値の指数として使用されま す。例えば、bInterval を 4 にすると、8 (24-1)の周期 になります。この値は 1～16 とします。 高速バルク／制御 OUT エンドポイントでは、 bInterval でエンドポイントの最大 NAK 率を指定する 必要があります。0 は、NAK が絶対に発生しないこと を示します。その他の値では、bInterval×マイクロ秒 ごとに NAK 数が高々1 となります。 この値は 0～255 の範囲内である必要があります。 USBX では USB エンドポイント記述子を次のように定義します。
typedef struct UX_ENDPOINT_DESCRIPTOR_STRUCT { UINT bLength; UINT bDescriptorType; UINT bEndpointAddress; UINT bmAttributes; USHORT wMaxPacketSize; UINT bInterval; } UX_ENDPOINT_DESCRIPTOR;
