注意 : この日本語版文書は参考資料としてご利用ください 最新情報は必ずオリジナルの英語版をご参照願います USB 組み込みホストスタック Author: はじめに USB は 各種の機器を PC に接続するための標準的な通信方式として普及しました フラッシュドライブやマウス等の汎用機器から特定アプリケーション向けの専用機器まで 他のシリアル通信プロトコルはほぼ完全に USB 規格に取って代わられました USB 規格では USB デバイス同士は直接通信できません USB デバイスは USB ホストとのみ通信でき USB ホストは 1 つまたは複数の USB デバイスが接続されたバスを制御します 最も一般的な USB ホストは PC です USB On-The-Go (OTG) モジュールを内蔵した Microchip 社製マイクロコントローラの導入により 組み込みアプリケーションで各種の USB 機器を USB 組み込みホストとして使う事が可能になりました USB の概要 Kim Otten Microchip Technology Inc. USB 動作の詳細を記載した参考資料は USB 2.0 仕様書以外にも多数存在します 以下では 本書で使う用語またはスタック動作を理解するために必要な用語について簡単に説明します USB ホストとペリフェラルデバイス 標準的な USB システムは 1 つのホストと 1 つまたは複数のペリフェラルデバイス ( 多くの場合 単に デバイス と呼ぶ ) によって構成されます 各デバイスはホストとのみ通信でき デバイス同士が直接通信する事はできません バス上の全ての通信は ホストによって開始されます デバイスは ホストから要求された時にのみデータをホストに向けて送信でき ホストから送信されたデータを受信する必要があります デバイスは通常 Type-B レセプタクルを使うか キャプティブケーブルを備えています ほとんどの USB ペリフェラルデバイスは いずれかのカテゴリ ( クラスと呼ぶ ) に分類されます クラスごとに通信フォーマットに関する要件が異なります ホストはデバイスのクラスを識別し そのクラスの要件を満たす必要があります この要件を満たせない場合 ホストはデバイスと通信できません クラスには マウス等に使われる HID (Human Interface Device) クラスや フラッシュドライブに使われるマスストレージクラス等があります クライアントドライバは これらのクラスに対してアプリケーションレベルのサポートを提供します USB ペリフェラルデバイスによっては ベンダー固有の仕様を持ち 既存のどのクラスにも分類されない物もあります それらのデバイスに対しては クライアントドライバのコードを専用に書く必要があります ホストに接続可能なデバイスの数は ハブを使う事で増やせます USB は階層式スター型ネットワークです 通常 ハブを使う事で 1 つのポートに 4 個または 7 個のデバイスを接続できます ハブは 最大で 5 個までデイジーチェーン接続できます ( 最大で 5 層を形成 ) バスには最大で 127 個のデバイス ( ハブを含む ) を接続できます 完全な USB ホストは Type-A レセプタクルを使って全てのデバイスと通信できる必要があります このサポートを提供するために 専用ドライバを使う事ができます 専用ドライバはデバイスを接続する前にホストにインストールしておく必要があります また ハブをサポートする必要があり 各ポートは 100 ma 以上を供給可能である事が必要です ホストと組み込みホスト USB 組み込みホストと通常の USB ホストの間には 小さいながらも重要な相違点がいくつかあります USB 組み込みホストは以下の点で通常の組み込みホストと異なります 特定ペリフェラルデバイスおよび / または特定クラスのデバイスのみをサポートする サポートするデバイスが要求する転送タイプのみをサポートする ハブのサポートは必須ではない 電源要件は軽減される これらの制限により 組み込みホストはメモリが固定された容量に限りのあるデバイスでも実装可能です 2014 Microchip Technology Inc. DS01140A_JP - p. 1
ホストモードの動作 USB システムでは ホストがバス上の全てのトラフィックを制御し デバイスはホストからの要求に応答する事しかできません ( デバイスからデータ転送を開始する事はできません ) USB OTG モジュールは ホストおよびデバイスのどちらのモードでも使えます 正確な動作方法は 2 つのモード間で異なります USB 転送は複数のトランザクションで構成でき トランザクションは複数のパケットで構成できます さらに 単一の転送は複数のデータステージトランザクションを含む事ができます 図 1 に 単一 USB 転送の一般的フォーマットを示します 図 1: 一般的な転送の構造 DS01140A_JP - p. 2 2014 Microchip Technology Inc.
多くの場合 コントロール転送には 3 種類のトランザクションの全てが必要です 8 個のデータバイトを読み出すコントロール転送の構造を図 2 に示します 図 2: コントロール転送の構造 2014 Microchip Technology Inc. DS01140A_JP - p. 3
バルク インタラプト アイソクロナス転送はセットアップステージとステータスステージのトランザクションを使いません バルク転送の場合 1 つのデータステージトランザクションで最大 64 バイトを転送でき ます 128 個のデータバイトを書き込むバルク転送には 2 つのデータステージトランザクションが必要です この転送の構造を図 3 に示します 図 3: バルク転送の構造 USB 組み込みホストスタックは ホストモードの USB OTG モジュールとパケットレベルで連携します ( 例外として ACK パケットはモジュールによって自動的に処理される ) 組み込みホストが図 3 のバルク転送を開始する場合 2 個の OUT パケットと 2 個の DATA0/ 1 パケットを転送するための命令を明示的に発行する必要があります 組み込みホストが図 2 のコントロール転送を開始する場合 SETUP DATA0/1 IN OUT パケットの全て ( 全部で 6 個のパケット ) を送信するための命令を明示的に発行する必要があります DS01140A_JP - p. 4 2014 Microchip Technology Inc.
USB 組み込みホスト TPL (Targeted Peripheral List) TPL (Targeted Peripheral List) は USB 組み込みホストがサポートするペリフェラルデバイスのリストです TPL 内の各エントリは 特定の製品 ( 製品の VID と PID を指定 ) または特定のクラス ( クラス サブクラス プロトコルを指定 ) を参照します 例として USB フラッシュドライブと Microchip 社の PICDEM FS USB デモボードをサポートする組み込みホストの TPL を表 1 に示します 表 1: 組み込みホストの TPL 名称 クラス名 クラスコード サブクラスコード プロトコル Flash Drive Mass Storage 0x08 0x06 0x50 名称 メーカー モデル VID PID Full-Speed Demo Microchip PICDEM FS USB 0x04D8 0x000C デュアルロールデバイスと On-The-Go デバイスは 2 つのレセプタクルを使って組み込みホストと USB デバイスの両方の機能をサポートする事で デュアルロールデバイスとして機能できます 例えばデジタルカメラは 画像を PC へダウンロードする時にペリフェラルデバイスとして動作し 画像をプリンタへ転送する時に組み込みホストとして動作できます カメラは 接続されたケーブルに応じて デバイスまたはホストどちらかのロールで動作します Type-A レセプタクルにケーブルを接続した場合 カメラはホストとして動作します Type-B レセプタクルにケーブルを接続した場合 カメラはデバイスとして動作します 常にどちらか一方のレセプタクルにのみアクセス可能な構造ではない限り Type-A および Type-B レセプタクルは同時に動作する必要があります USB On-The-Go デバイスとは ケーブルを差し換えずにロールを組み込みホストからペリフェラルデバイスへ動的に変更できるデバイスです OTG デバイスは micro-ab レセプタクルを使います 初期のロールはケーブルの向きによって決まります ケーブルの micro-a プラグが挿入されたデバイスは 組み込みホ ストとして動作するよう初期設定されます ケーブルの micro-b プラグが挿入されたデバイスは ペリフェラルデバイスとして動作するよう初期設定されます OTG 機能を使うかどうかの選択は 2 つのデバイスのロールを動的に切り換える必要があるかどうかによって決まります ほとんどの場合 互いに通信する 2 つのデバイスのロール ( ホスト / ペリフェラル ) は固定されています 例えば 上記のデュアルロールデジタルカメラの場合 PC またはプリンタとの間でロールを交替する必要がないため OTG 機能は不要です また On-The-Go デバイスの TPL には制約があります OTG デバイスの TPL では サポートする個々のデバイスを指定する必要があります ( サポートするクラスを指定する事はできません ) 例えば OTG デバイスでは USB フラッシュドライブをマスストレージクラスとして全般的にサポートする事はできません OTG デバイスは OTG 非対応ペリフェラルデバイスをサポートできますが そのペリフェラルデバイスの VID と PID を指定する必要があります Microchip 社の PICDEM FS USB デモをサポートする OTG デバイスの TPL の例を表 2 に示します 表 2: OTG TPL 名称 メーカー モデル VID PID Full-Speed Demo Microchip PICDEM FS USB 0x04D8 0x000C 2014 Microchip Technology Inc. DS01140A_JP - p. 5
USB 組み込みホストスタック Microchip 社は 弊社製マイクロコントローラ向けに ロイヤリティフリーで USB 組み込みホストスタックを提供しています このスタックは USB OTG モジュールを内蔵する全ての Microchip 社製デバイス上で動作します 各種のコンパイル時オプションを使ってスタックの動作を設定する事で 特定のアプリケーション向けに速度とサイズを最適化できます スタックはステートマシンに基づき 割り込みとポーリングの両方を使います 割り込みは実行時間が重要な全ての動作向けに使い 実行時間が重要ではない動作の処理にはポーリングを使います どちらも スタックが適正に動作するように使う必要があります ポーリングを使わずに 特定システムイベントの発生を通知するようにスタックを設定する事もできます スタックのインストール USB サポートパッケージは Microchip 社のウェブサイト (http://www.microchip.com/usb) からダウンロードできます ウェブサイトから必要なインストールパッケージをダウンロードして実行してください 一部の USB デモは 他のアプリケーションノートからのライブラリを使います それらのライブラリもインストールされます 既定値では USB ホストスタックファイルは図 4 に示すディレクトリ構造にインストールされます 図 4: インストールディレクトリ構造 Local Hard Drive (C:) + + Microchip Solutions + + + + Microchip + + Common Generic Microchip Source Files Include USB USB USB Header Files Generic Microchip Header Files Documents Client Driver Directories USBConfig.exe USB Source Files Help Help Files + USB Data Logger Project Files DS01140A_JP - p. 6 2014 Microchip Technology Inc.
スタックアーキテクチャ USB 組み込みホストスタックはモジュール構造を持ち ノンブロッキング RTOS 非依存です このスタックは以下の 2 つのメインセクションによって構成されます ステートマシン - バックグラウンド処理用 ( デバイスエニュメレーション等 ) 割り込みハンドラ 実行時間が重要な処理向けにバスを効率的に使用ステートマシンの構造を図 5 に示します 図 5: USB 組み込みホストのステートマシン INIT Attach Interrupt DETACHED STATE Validation Failed Deattach Interrupt ATTACHED STATE Validation Successful Deattach Interrupt Deattach Interrupt ADDRESSING STATE Deattach Interrupt RUNNING STATE Device Deconfigured Address Assigned Device Configured CONFIGURING STATE 2014 Microchip Technology Inc. DS01140A_JP - p. 7
デバイスが動作ステートに移行すると スタックは初期化イベントハンドラを呼び出す事によって 新たにエニュメレートされたデバイスをクライアントドライバに知らせます このイベントハンドラの詳細は イベントハンドラの定義 を参照してください クライアントドライバが正常に初期化されると 通常の通信が始まります USB バスは 1 ms のフレームを使って動作します このフレーム内で複数メッセージを送信できます 従って 高速に応答して USB トラフィックを効果的に制御するために 割り込みを使います スタックは以下の 2 種類の重要割り込みを使います SOF (Start-Of-Frame) 割り込み - USB OTGモジュールが新しい 1 ms フレームを開始する直前に生成される トランザクション完了割り込み - USB OTG モジュールが最後に要求されたトランザクションを完了した時点で生成される これらの割り込みを受信すると 割り込みサービスルーチン (ISR) はバス上で送信する次のトランザクション ( 存在する場合 ) を決定します スタックの設定 図 4 のディレクトリ構造内にインストールされるコンフィグレーションツール (USBConfig.exe) を使うと USB ホストスタックとクライアントドライバを特定のアプリケーション向けに設定できます 図 6 に示すように 最初に [Main] タブで [Device Type] と [Ping-Pong Mode] を指定します [Device Type] を指定すると それに応じた適切なコンフィグレーションパラメータが 他のタブ上で設定可能になります これらのパラメータを使って ホスト / デバイスと必要なクライアントドライバを設定します 図 6: USB コンフィグレーションツール - [MAIN] タブ DS01140A_JP - p. 8 2014 Microchip Technology Inc.
[Device Type] で USB Emgedded Host USB Dual Role USB OTG のいずれかを指定した場合 図 7 に示す [Host] タブ上でホストモードを設定できます エンドポイントサポートを調整する事で プログラムメモリを節約できます [Attach Debounce Interval (ms)] の値を USB 仕様値 (100 ms) よりも大きくする事で より低速のデバイスをサポートできます [Name of Application Event Handler] には アプリケーションレベルのイベントハンドラとして機能するメインソースファイル内の関数の名前を入力する必要があります 転送イベントを使う場合 [Generate Transfer Events] にチェックマークを付ける必要があります 転送イベントの使用方法については 転送イベントの使用 を参照してください 図 7: USB コンフィグレーションツール - [HOST] タブ 2014 Microchip Technology Inc. DS01140A_JP - p. 9
TPL は 図 8 に示す [TPL] タブで指定できます VID/ PID またはクラスのどちらかを指定できます TPL の詳細については TPL (Targeted Peripheral List) を参照してください 図 8: USB コンフィグレーションツール - [TPL] タブ アプリケーションに固有のクラスサポートは 別のタブを使って指定できます クラスとそれらのクライアントドライバに関する詳細については 別冊の USB 関連アプリケーションノートを参照してください PIC24F の要件 USB OTG モジュールには 48 MHz クロックが必要です これは最大 CPU クロックレートを超えているため 1 つのオシレータソースから CPU クロックと USB クロックの両方を生成するための方法が用意されています オシレータソースは 4 MHz の整数倍の周波数で動作する必要があります この周波数は USB PLL プリスケーラを使って 4 MHz に分周する必要があります USB PLL プリスケーラは 入力されるオシレータ周波数を自動的に検出しません 4 MHz のプリスケーラ出力を生成するには ユーザが手動で PLL 分周比 (PLLDIV2:PLLDIV0 コンフィグレーションビット ) を適切に設定する必要があります このため プライマリオシレータ周波数の選択肢は表 3 に示す 8 通りに制限されます Note: FRC オシレータの許容誤差は USB 仕様の許容誤差よりも大きいため FRC の使用は推奨しません 表 3: PIC24F USB 動作向けのプライマリオシレータ設定 入力オシレータ周波数 クロックモード PLL 分周比 (PLLDIV<2:0>) 48 MHz ECPLL 12 (111) 40 MHz ECPLL 10 (110) 24 MHz HSPLL, ECPLL 6 (101) 20 MHz HSPLL, ECPLL 5 (100) 16 MHz HSPLL, ECPLL 4 (011) 12 MHz HSPLL, ECPLL 3 (010) 8 MHz HSPLL, ECPLL 2 (001) 4 MHz HSPLL, ECPLL, XTPLL 1 (000) DS01140A_JP - p. 10 2014 Microchip Technology Inc.
USB PLL 出力を使って内蔵 96 MHz PLL 周波数逓倍器を駆動し その出力は 2 つのクロック回路に分岐されます 一方の分岐は 2 分周 ( 固定 ) の分周器を使って 48 MHz の USB クロックを生成します 他方の分岐は 3 分周 ( 固定 ) の分周器と設定可能 PLL プリスケーラ / 分周器 (CLKDIV<CPDIV1:0>) を使って 所定レンジのシステムクロック周波数を生成します 表 4 に 利用可能なシステムクロックオプションを示します オシレータモードの詳細については マイクロコントローラのデータシートを参照してください 表 4: USB 動作時のシステムクロックオプション MCU クロック分周比 (CPUDIV<1:0>) 分周せず (00) 2??(01) 4??(10) 8??(11) PIC32 の要件 MCU クロック周波数 32 MHz 16 MHz 8 MHz 4 MHz Note: その他の選択可能クロックオプションまたは制約事項に関しては 各デバイスのデータシートを参照してください USB OTG モジュールには 48 MHz のクロックが必要です このクロックは 以下の 3 通りの方法で供給できます 8 MHz FRC 内部オシレータを使う OSC1/OSC2 ピンに 48 MHz オシレータを供給する OSC1/OSC2 から 96 MHz USB PLL を使う USB PLL は UPLLEN コンフィグレーションビットで有効にします OSC1/OSC2 ピン上のオシレータソースは 4MHzの整数倍の周波数で動作する必要があります この周波数は USB PLL プリスケーラを使って 4 MHz に分周する必要があります USB PLL プリスケーラは 入力されるオシレータ周波数を自動的に検出しません 4 MHz 出力を生成するには ユーザが手動でPLL 分周比 (UPLLIDIVコンフィグレーションビット ) を適切に設定する必要があります 次に 96 MHz PLL 出力を 2 分周 ( 固定 ) の分周器に入力して 48 MHz の USB クロックを生成します システムバスおよび周辺モジュールバスクロックは USB PLL の使用によって影響を受けません あるいは サスペンドモードからの復帰時に USB モジュール向けのクロック源が必要な場合 FRC を使う事ができます FRC ソースは OSCCON<UFRCEN> ビットで選択します Note: その他の選択可能クロックオプションまたは制約事項に関しては 各デバイスのデータシートを参照してください プロジェクト要件 USB 組み込みホストスタックは 接続デバイスに関する情報を動的メモリに保存します USB ペリフェラルのデバイスディスクリプタ 全てのコンフィグレーションディスクリプタ 64 バイトのオーバーヘッド用に十分なヒープ空間を割り当てる必要があります クライアントドライバは 追加の動的メモリを要求する場合があります デバイス情報を保持するために十分な動的メモリが得られない場合 デバイスはエニュメレーションに失敗します ヒープサイズは MPLAB IDE プロジェクト内で MPLAB IDE メインメニューから Project>Build Options >Project を選択する事で指定できます 16 ビットマイクロコントローラを使う場合 [MPLAB LINK30] タブを開いて [Heap Size] 編集ボックスに値を入力します 次いで [OK] をクリックします スタックの使用方法 ほとんどのアプリケーションは USB 組み込みホストスタックと直接連携しません その代わりに クライアントドライバを使います ( クライアントドライバが代わりにホストスタックを使用します ) アプリケーションによっては クライアントドライバと連携する追加のレイヤを備える場合があります 例えば AN1145 - 組み込みホストにおける USB フラッシュドライブの使用 に記載したアプリケーションは 図 9 に示すように アプリケーション層を含む 5 つのレイヤを使います 図 9: USB フラッシュドライブのデータロガーアーキテクチャ Application Layer File System Support SCSI Command Support Mass Storage Client Driver USB Host Driver 本書の内容は 主にクライアントドライバの開発者を対象としています Note: USB 組み込みホストスタック API の詳細については Help ディレクトリ内の API 関連文書と AN1141 - USB 組み込みホストスタックプログラマガイド を参照してください 2014 Microchip Technology Inc. DS01140A_JP - p. 11
TPL の定義 サポート可能な USB ペリフェラルデバイスをスタックに知らせるために TPL (Targeted Peripheral List) を定義する必要があります アプリケーションが USB OTG を使う場合 TPL にはサポートする個々のデバイス ( 各デバイスに固有の VID/PID ペア ) だけを含める事ができます アプリケーションが USB 組み込みホストを使う場合 TPL にはサポートする個々のデバイス ( 固有の VID/OID ペア ) に加えて サポートするクラスも含める事ができます TPL は スタックと一緒に提供されるコンフィグレーションツール (USBConfig.exe) を使って定義できます スタックの設定 を参照してください イベントハンドラの定義 クライアントレベルのイベント スタックは クライアントドライバ内で 2 つのイベントハンドラを必要とします 1 つはデバイス初期化ハンドラです これは デバイスのコンフィグレーションが設定された後 デバイスエミュレーション中に呼び出されます デバイス初期化ハンドラは 以下のように typedef で定義された関数である事が必要です typedef BOOL (*USB_CLIENT_INIT) ( BYTE address, DWORD flags ); この関数は デバイスのクラスに固有のデバイス初期化を実行します 初期化中にエラーが発生しなかった場合 このルーチンは TRUE を返します エラーが発生した場合 このルーチンは FALSE を返し デバイスはエニュメレートされません 例 1 に 初期化ハンドラのサンプルコードを示します 例 1: 初期化ハンドラ BOOL USBHostSampleInitialize( BYTE address, DWORD flags ) // This handler supports one attached device. if (devicehandle!= 0) return FALSE; // We cannot support this device. devicehandle = address; // Initialize something based on flags. if (flags & 0x01) // Do something else // Do something else return TRUE; // Device successfully initialized DS01140A_JP - p. 12 2014 Microchip Technology Inc.
2 つめのイベントハンドラは 通常動作中に発生するイベントを処理するために必要です このイベントハンドラは 以下のように typedef で定義された関数である事が必要です typedef BOOL (*USB_CLIENT_EVENT_HANDLER) ( BYTE address, USB_EVENT event, void *data, DWORD size ); 発生する可能性のあるイベントの例として EVENT_DETACH があります このイベントは デバイスがバスから切断された時に発生します この場合 クライアントドライバのステータスを更新する必要があります この更新は そのクライアントドライバを使う接続デバイスのリストから 切断されたデバイスを削除する等の動作によって行います 例 2 に イベントハンドラのサンプルを示します 例 2: イベントハンドラ BOOL USBHostSampleEventHandler( BYTE address, USB_EVENT event, void *data, DWORD size ) switch (event) case EVENT_DETACH: devicehandle = 0; return TRUE; break; // More events handled here return FALSE; // We did not handle the event OTG 動作向けに各種のイベントが提供されます 加えて 転送イベント (EVENT_TRANSFER) を提供するようにスタックを設定する事もできます 転送イベントの使用 を参照してください イベントの完全なリストは Help ディレクトリ内の API 関連文書に記載されています スタックは サポートする各クライアントドライバの全ての初期化およびイベントハンドラを含むリストを要求します このリストは スタックと一緒に提供されるコンフィグレーションツール (USBConfig.exe) を使って定義できます スタックの設定 を参照してください 2014 Microchip Technology Inc. DS01140A_JP - p. 13
アプリケーションレベルのイベント 一部のイベントは クライアントドライバレベルではなく最上位のアプリケーションレベルを対象とします この種のイベントの代表例が EVENT_REQUEST_POWER です このイベントは エニュメレーションの処理中にデバイスが電源を要求した時に生成されます 接続デバイスに割り当てる電力量をアプリケーションで監視または制御する必要がある場合 アプリケーションイベントハンドラを実装する必要があ ります このイベントハンドラの型も 上記の USB_CLIENT_EVENT_HANDLER である事が必要です イベントハンドラの名前は コンフィグレーションツール (USBConfig.exe) の [Host] タブ内の [Name of Application Event Handler] フィールドに入力する必要があります ( スタックの設定 参照 ) 例 3 に 電源を制御するための最小限のイベントハンドラを示します 例 3: アプリケーションレベルのイベントハンドラ BOOL USB_ApplicationEventHandler( BYTE address, USB_EVENT event, void *data, DWORD size ) switch( event ) case EVENT_REQUEST_POWER: // data points to a byte that represents the amount // of power requested in ma, divided by two. if (*(BYTE*)data > 50) // We will allow up to 100mA return FALSE; break; return TRUE; // Allow all other events to pass. イベントハンドラが何も実装されていない場合 組み込みホストスタックは イベントハンドラが TRUE を返したかのように応答します スタックの初期化 USB 組み込みホストの動作は 以下の 1 つの関数によって初期化されます BYTE USBHostInit( void ); この関数は スタック動作の全ての内部変数を初期化します この関数は アプリケーションの実行中に 1 度だけ呼び出します マイクロコントローラ上の USB OTG モジュールは この関数内で設定されません USB コンフィグレーションツールは USB ホストドライバとサポートするクライアントドライバが要求する全ての初期化ルーチンを呼び出すためのマクロ (USBInitialize()) を生成します Note: アプリケーションは より低レベルの関数呼び出しの代わりに USBInitialize() マクロを使う必要があります 通常のスタック動作 初期化後は 以下の 1 つの関数によって USB OTG モジュールコンフィグレーションと USB 組み込みホスト動作がトリガされます void USBHostTasks( void ); この関数は デバイスをエニュメレートするために必要なステートマシンを実行します 適切なタイミングでエニュメレーションを行うために この関数は一定間隔で呼び出す必要があります USB コンフィグレーションツールは USB ホストドライバとサポートするクライアントドライバが要求する全てのタスクルーチンを呼び出すためのマクロ (USBTasks()) を生成します Note: アプリケーションは より低レベルの関数呼び出しの代わり USBTasks() マクロを使う必要があります ペリフェラルデバイスとの通信 Note: 以下では ペリフェラルデバイスと通信するためにクライアントドライバ向けに必要なルーチンについて説明します アプリケーションレベルのコードはこれらの関数を呼び出さず 代わりにクライアントドライバ内の適切なルーチンを使います デバイスとの通常の通信は 以下の 2 つの関数によって開始されます BYTE USBHostRead( BYTE deviceaddress, BYTE endpoint, BYTE *data, DWORD size ); BYTE USBHostWrite( BYTE deviceaddress, BYTE endpoint, BYTE *data, DWORD size ); USB_SUCCESS (0x00) の戻り値は 動作が正常に始まった事を示します DS01140A_JP - p. 14 2014 Microchip Technology Inc.
通信が始まった後は 動作のステータス ( 完了したかどうか ) を監視しながら USBTasks() (USBHostTasks() と必要な全てのクライアントタスク ) を実行するよう注意してください 動作ステータスは 以下の関数を呼び出す事で判定できます BOOL USBHostTransferIsComplete( BYTE deviceaddress, BYTE endpoint, BYTE *errorcode, DWORD *bytecount ); この関数が FALSE を返した場合 転送は未完了であり 返されたエラーコードとバイトカウントは無効です この関数が TRUE を返した場合 返されたエラーコードは動作のステータスを示し 返されたバイトカウントは転送されたバイトの数を示します ホストからデバイスへのデータ転送の例を例 4 に示します 例 4: ペリフェラルデバイスへのデータ送信 error = USBHostWrite( device, EP1, buffer, sizeof(buffer) ); if (error) // There was a problem else while (!USBHostTransferIsComplete( device, EP1, &error, &count )) USBHostTasks(); if (error) // There was a problem else // The data was transferred successfully 2014 Microchip Technology Inc. DS01140A_JP - p. 15
スタックの高度な使用方法 転送イベントの使用 例 4 に示したデータ転送の方法は簡単ですが 転送の完了を待機している間は実行がループ内でトラップされるという欠点があります これを防ぐ 1 つの方法として 転送イベントを使います 基本的なスタック動作向けに特定のイベントをサポートする必要があるため 全てのクライアントドライバはイベントハンドラを備える必要があります しかし転送イベントは必須ではありません なぜならば 全てのアプリケーションが転送イベントを必要とするわけではなく また 転送イベントによって必要リソースが増加するからです 転送イベントは システム内の他のイベントとは異なる方法で動作します USB 転送の完了ステータスは 転送完了割り込みの発生時に USB ISR 内で判定されます しかし この時点では 転送イベントは生成されません バスを効率的に使うには 1 USB フレーム (1 ms) 内で可能な限り多くのトランザクションを実行するために USB 割り込みをできるだけ短くする必要があります クライアントドライバのイベントハンドラは比較的サイズが大きく 実行に長い時間を要する場合があります また アプリケーションの別のレイヤによる処理が必要な別のイベントが発生する可能性があり その場合は非常に長い遅延が生じます このため 転送イベントキューを使います 転送イベント (EVENT_TRANSFER) は ISR 内で HOST_TRANSFER_DATA 型の構造体と一緒にキューに入れられます これにより アプリケーションは どの転送が完了したのかと その転送が成功したかどうかを判定できます 関数 USBHostTasks() は 転送イベントをキューから取り出し それらをクライアントドライバのイベントハンドラへ引き渡します 一般的に 転送イベントをサポートする場合 転送イベントキューのために プログラムメモリとデータメモリの必要量が増加します コードアーキテクチャが複雑化するため C 言語プログラミングの初心者がこのアーキテクチャを設計 開発 デバッグ 維持する事はより難しくなります しかし転送イベントを使う事で クライアントドライバのバックグラウンドタスク処理関数を最小限に ( あるいは不要に ) して 処理帯域幅をより効率的に活用できます 転送の終了スタックは デバイスが送信する NAK の数をカウントする事で デバイスが応答に失敗している転送を自動的に終了できます アプリケーションがこれとは異なるタイムアウトを必要とする場合 以下の関数を呼び出す事によって転送を手動で終了できます void USBHostTerminateTransfer( BYTE deviceaddress, BYTE endpoint ); 標準デバイスリクエストの発行 全ての USB デバイスは ホストからの特定の要求に応答します アプリケーションは 以下の関数を呼び出す事によって USB 標準デバイスリクエストを発行できます BYTE USBHostDeviceRequest( BYTE deviceaddress, BYTE bmrequesttype, BYTE brequest, WORD wvalue, WORD windex, WORD wlength, BYTE *data, BYTE datadirection ); その後 スタックは要求されたコントロール転送をエンドポイント 0 上で開始します 標準デバイスリクエストの詳細は USB 2.0 仕様書を参照してください エンドポイントエラーのクリア 発生エラー数が多すぎるために転送に失敗した場合 またはデバイスがエンドポイントをストールさせたために転送に失敗した場合 別の転送を試みる前にエラーをクリアする必要があります エラー条件は 以下の関数を呼び出す事によってクリアできます BYTE USBHostClearEndpointErrors( BYTE deviceaddress, BYTE endpoint ); ストールが発生した場合 USBHostClearEndpointErrors() を呼び出すと共に デバイス上のストール条件をクリアする必要があります これを行うには CLEAR FEATURE デバイスリクエストを ENDPOINT HALT 機能セレクタと現在ストール中のエンドポイント番号を使って発行します ( 標準デバイスリクエストの発行 参照 ) CLEAR FEATURE デバイスリクエストの詳細は USB 2.0 仕様書を参照してください デバイスおよびコンフィグレーションディスクリプタへのアクセスエニュメレーション中に スタックはデバイスディスクリプタと そのデバイスのコンフィグレーションディスクリプタを取得して保存します クライアントドライバは USBHostGetDeviceDescriptor() 関数を使ってデバイスディスクリプタにアクセスできます この関数は デバイスディスクリプタを指すポインタを返します BYTE * USBHostGetDeviceDescriptor( BYTE deviceaddress ); クライアントドライバは USBHostGetCurrentConfigurationDescriptor() 関数を使う事で 現在のコンフィグレーションのコンフィグレーションディスクリプタにアクセスする事もできます この関数も ディスクリプタを指すポインタを返します BYTE * USBHostGetCurrentConfigurationDescriptor ( BYTE deviceaddress ) DS01140A_JP - p. 16 2014 Microchip Technology Inc.
ストリングディスクリプタの取得 USB ペリフェラルデバイスには製品 メーカー デバイスシリアル番号等の文字列情報を記述したストリングディスクリプタを格納できます 必要な文字列のインデックスは デバイスディスクリプタ内の適切なフィールドを参照する事で取得できます 次に以下の関数を呼び出す事で 必要な文字列を取得できます BYTE USBHostGetStringDescriptor ( BYTE deviceaddress, BYTE stringnumber, BYTE *stringdescriptor, BYTE stringlength ) 例 5 に 接続デバイスのシリアル番号を取得する方法を示します デバイスディスクリプタとストリングディスクリプタの詳細については USB 2.0 仕様書を参照してください 例 5: デバイスシリアル番号の取得 devicedescriptor = USBHostGetDeviceDescriptor( device ); snindex = devicedescriptor[16]; //See Device Descriptor spec. if (snindex!= 0) if (!USBHostGetStringDescriptor( device, snindex, buffer, 50 )) while(!usbhosttransferiscomplete( device, 0, &error, &count )) USBHostTasks(); if (!error) // Serial number is in buffer[] in UNICODE 2014 Microchip Technology Inc. DS01140A_JP - p. 17
まとめ Microchip 社製 16 および 32 ビットマイクロコントローラ向けの USB 組み込みホストスタックは 各種の USB クラスをサポートするためのプラットフォームを提供します これらのソリューションを使う事で マスストレージおよびヒューマンインターフェイスデバイスを含む各種の USB ペリフェラルデバイスをアプリケーションで使用できます 一部の Microchip 社製 16 および 32 ビットマイクロコントローラが内蔵する USB OTG モジュールの USB 組み込みホスト機能は 組み込みアプリケーションに全く新しい境地を開きます 参考資料 AN1141 - USB 組み込みホストスタックプログラマガイド (http://www.microchip.com) AN1142 - 組み込みホストにおける USB マスストレージクラス (http://www.microchip.com) AN1143 - 組み込みホストにおける USB 汎用クライアント (http://www.microchip.com) AN1143 - 組み込みホストにおける USB HID クラス (http://www.microchip.com) AN1145 - 組み込みホストにおける USB フラッシュドライブの使用 (http://www.microchip.com) Universal Serial Bus ウェブサイト (http://www.usb.org) Microchip 社ウェブサイト (http://www.microchip.com) DS01140A_JP - p. 18 2014 Microchip Technology Inc.
Microchip 社製デバイスのコード保護機能に関して次の点にご注意ください Microchip 社製品は 該当する Microchip 社データシートに記載の仕様を満たしています Microchip 社では 通常の条件ならびに仕様に従って使用した場合 Microchip 社製品のセキュリティレベルは 現在市場に流通している同種製品の中でも最も高度であると考えています しかし コード保護機能を解除するための不正かつ違法な方法が存在する事もまた事実です 弊社の理解ではこうした手法は Microchip 社データシートにある動作仕様書以外の方法で Microchip 社製品を使用する事になります このような行為は知的所有権の侵害に該当する可能性が非常に高いと言えます Microchip 社は コードの保全性に懸念を抱くお客様と連携し 対応策に取り組んでいきます Microchip 社を含む全ての半導体メーカーで 自社のコードのセキュリティを完全に保証できる企業はありません コード保護機能とは Microchip 社が製品を 解読不能 として保証するものではありません コード保護機能は常に進歩しています Microchip 社では 常に製品のコード保護機能の改善に取り組んでいます Microchip 社のコード保護機能の侵害は デジタルミレニアム著作権法に違反します そのような行為によってソフトウェアまたはその他の著 本書に記載されているデバイスアプリケーション等に関する情報は ユーザの便宜のためにのみ提供されているものであり 更新によって無効とされる事があります お客様のアプリケーションが仕様を満たす事を保証する責任は お客様にあります Microchip 社は 明示的 暗黙的 書面 口頭 法定のいずれであるかを問わず 本書に記載されている情報に関して 状態 品質 性能 商品性 特定目的への適合性をはじめとする いかなる類の表明も保証も行いません Microchip 社は 本書の情報およびその使用に起因する一切の責任を否認します Microchip 社の明示的な書面による承認なしに 生命維持装置あるいは生命安全用途に Microchip 社の製品を使用する事は全て購入者のリスクとし また購入者はこれによって発生したあらゆる損害 クレーム 訴訟 費用に関して Microchip 社は擁護され 免責され 損害をうけない事に同意するものとします 暗黙的あるいは明示的を問わず Microchip 社が知的財産権を保有しているライセンスは一切譲渡されません 商標 Microchip 社の名称と Microchip ロゴ dspic FlashFlex KEELOQ KEELOQ ロゴ MPLAB PIC PICmicro PICSTART PIC 32 ロゴ rfpic SST SST ロゴ SuperFlash UNI/O は 米国およびその他の国における Microchip Technology Incorporated の登録商標です FilterLab Hampshire HI-TECH C Linear Active Thermistor MTP SEEVAL Embedded Control Solutions Company は 米国における Microchip Technology Incorporated の登録商標です Silicon Storage Technology は その他の国における Microchip Technology Incorporated の登録商標です Analog-for-the-Digital Age Application Maestro BodyCom chipkit chipkit ロゴ CodeGuard dspicdem dspicdem.net dspicworks dsspeak ECAN ECONOMONITOR FanSense HI-TIDE In-Circuit Serial Programming ICSP Mindi MiWi MPASM MPF MPLAB 認証ロゴ MPLIB MPLINK mtouch Omniscient Code Generation PICC PICC-18 PICDEM PICDEM.net PICkit PICtail REAL ICE rflab Select Mode SQI Serial Quad I/O Total Endurance TSHARC UniWinDriver WiperLock ZENA Z-Scale は 米国およびその他の国における Microchip Technology Incorporated の登録商標です SQTP は 米国における Microchip Technology Incorporated のサービスマークです GestICとULPPは その他の国におけるMicrochip Technology Germany II GmbH & Co. & KG (Microchip Technology Incorporated の子会社 ) の登録商標です その他 本書に記載されている商標は各社に帰属します 2013, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved. ISBN: 978-1-63276-119-4 QUALITY MANAGEMENT SYSTEM CERTIFIED BY DNV == ISO/TS 16949 == Microchip 社では Chandler および Tempe ( アリゾナ州 ) Gresham ( オレゴン州 ) の本部 設計部およびウェハー製造工場そしてカリフォルニア州とインドのデザインセンターが ISO/TS-16949:2009 認証を取得しています Microchip 社の品質システムプロセスおよび手順は PIC MCU および dspic DSC KEELOQ コードホッピングデバイス シリアル EEPROM マイクロペリフェラル 不揮発性メモリ アナログ製品に採用されています さらに 開発システムの設計と製造に関する Microchip 社の品質システムは ISO 9001:2000 認証を取得しています 2014 Microchip Technology Inc. DS01140A_JP - p. 19
各国の営業所とサービス 北米本社 2355 West Chandler Blvd. Chandler, AZ 85224-6199 Tel:480-792-7200 Fax:480-792-7277 技術サポート : http://www.microchip.com/ support URL: www.microchip.com アトランタ Duluth, GA Tel:678-957-9614 Fax:678-957-1455 オースティン (TX) Tel:512-257-3370 ボストン Westborough, MA Tel:774-760-0087 Fax:774-760-0088 シカゴ Itasca, IL Tel:630-285-0071 Fax:630-285-0075 クリーブランド Independence, OH Tel:216-447-0464 Fax:216-447-0643 ダラス Addison, TX Tel:972-818-7423 Fax:972-818-2924 デトロイト Novi, MI Tel:248-848-4000 ヒューストン (TX) Tel:281-894-5983 インディアナポリス Noblesville, IN Tel:317-773-8323 Fax:317-773-5453 ロサンゼルス Mission Viejo, CA Tel:949-462-9523 Fax:949-462-9608 ニューヨーク (NY) Tel:631-435-6000 サンノゼ (CA) Tel:408-735-9110 カナダ - トロント Tel:905-673-0699 Fax:905-673-6509 アジア / 太平洋アジア太平洋支社 Suites 3707-14, 37th Floor Tower 6, The Gateway Harbour City, Kowloon Hong Kong Tel:852-2943-5100 Fax:852-2401-3431 オーストラリア - シドニー Tel:61-2-9868-6733 Fax:61-2-9868-6755 中国 - 北京 Tel:86-10-8569-7000 Fax:86-10-8528-2104 中国 - 成都 Tel:86-28-8665-5511 Fax:86-28-8665-7889 中国 - 重慶 Tel:86-23-8980-9588 Fax:86-23-8980-9500 中国 - 杭州 Tel:86-571-8792-8115 Fax:86-571-8792-8116 中国 - 香港 SAR Tel:852-2943-5100 Fax:852-2401-3431 中国 - 南京 Tel:86-25-8473-2460 Fax:86-25-8473-2470 中国 - 青島 Tel:86-532-8502-7355 Fax:86-532-8502-7205 中国 - 上海 Tel:86-21-5407-5533 Fax:86-21-5407-5066 中国 - 瀋陽 Tel:86-24-2334-2829 Fax:86-24-2334-2393 中国 - 深圳 Tel:86-755-8864-2200 Fax:86-755-8203-1760 中国 - 武漢 Tel:86-27-5980-5300 Fax:86-27-5980-5118 中国 - 西安 Tel:86-29-8833-7252 Fax:86-29-8833-7256 中国 - 厦門 Tel:86-592-2388138 Fax:86-592-2388130 中国 - 珠海 Tel:86-756-3210040 Fax:86-756-3210049 アジア / 太平洋 インド - バンガロール Tel:91-80-3090-4444 Fax:91-80-3090-4123 インド - ニューデリー Tel:91-11-4160-8631 Fax:91-11-4160-8632 インド - プネ Tel:91-20-3019-1500 日本 - 大阪 Tel:81-6-6152-7160 Fax:81-6-6152-9310 日本 - 東京 Tel:81-3-6880-3770 Fax:81-3-6880-3771 韓国 - 大邱 Tel:82-53-744-4301 Fax:82-53-744-4302 韓国 - ソウル Tel:82-2-554-7200 Fax:82-2-558-5932 または 82-2-558-5934 マレーシア - クアラルンプール Tel:60-3-6201-9857 Fax:60-3-6201-9859 マレーシア - ペナン Tel:60-4-227-8870 Fax:60-4-227-4068 フィリピン - マニラ Tel:63-2-634-9065 Fax:63-2-634-9069 シンガポール Tel:65-6334-8870 Fax:65-6334-8850 台湾 - 新竹 Tel:886-3-5778-366 Fax:886-3-5770-955 台湾 - 高雄 Tel:886-7-213-7830 台湾 - 台北 Tel:886-2-2508-8600 Fax:886-2-2508-0102 タイ - バンコク Tel:66-2-694-1351 Fax:66-2-694-1350 ヨーロッパオーストリア - ヴェルス Tel:43-7242-2244-39 Fax:43-7242-2244-393 デンマーク - コペンハーゲン Tel:45-4450-2828 Fax:45-4485-2829 フランス - パリ Tel:33-1-69-53-63-20 Fax:33-1-69-30-90-79 ドイツ - デュッセルドルフ Tel:49-2129-3766400 ドイツ - ミュンヘン Tel:49-89-627-144-0 Fax:49-89-627-144-44 ドイツ - プフォルツハイム Tel:49-7231-424750 イタリア - ミラノ Tel:39-0331-742611 Fax:39-0331-466781 イタリア - ベニス Tel:39-049-7625286 オランダ - ドリューネン Tel:31-416-690399 Fax:31-416-690340 ポーランド - ワルシャワ Tel:48-22-3325737 スペイン - マドリッド Tel:34-91-708-08-90 Fax:34-91-708-08-91 スウェーデン - ストックホルム Tel:46-8-5090-4654 イギリス - ウォーキンガム Tel:44-118-921-5800 Fax:44-118-921-5820 03/25/14 DS01140A_JP - p. 20 2014 Microchip Technology Inc.