UsbHLib USBホストCライブラリ

GitHubリポジトリ

概要

USBホストIPなどのハードウェアを制御してUSBホスト機能を実現するためのCライブラリです。現在はUSBホストIPとしてOpenCoresで公開されているUSBHostSlave IPCoreをサポートしています。

サポートしているUSBデバイス

HUB
Human Interface Devices

キーボード
マウス
ゲームパッド

Mass Storage Class Bulk-Only Transport

ディレクトリ構成

doc	ドキュメント
core	USBホストCライブラリのソースファイル
hw_dep	プラットフォーム依存部のソースファイル
- nios2	Nios2システム依存部
- microblaze	MicroBlazeシステム依存部
config_sample	Cライブラリ設定例
- all	すべてのサポートデバイスを利用する場合の設定ファイル例
- simple_mouse	マウスとHUBを利用する場合の設定ファイル例
- dev_attach_detach	HUBにマウスが取り付け/取り外しされた場合に発生するコールバック関数を利用する場合の設定例
- simple_keyboard	キーボードとHUBを利用する場合の設定ファイル例
- simple_gamepad	ゲームパッドとHUBを利用する場合の設定ファイル例
- simple_msd_bot	USBメモリ、カードリーダー等のストレージとHUBを利用する場合の設定ファイル例
microblaze	MicroBlazeを使用する場合の設定例
- all	すべてのサポートデバイスを利用する場合の設定ファイル例
- simple_mouse	マウスとHUBを利用する場合の設定ファイル例

ファイル構成

Cライブラリは、coreディレクトリのファイル、プラットフォームに応じたhw_depディレクトリのファイル、Cライブラリの設定を定義したconfig_sampleディレクトリのファイルで構成されます。
例) NiosIIプラットフォームでマウスとHUBを利用する場合のファイル構成


  coreのファイル+
  hw_dep/nios2のファイル+
  config_sample/simple_mouseのファイル

例)MicroBlazeプラットフォームで全サポートデバイスを利用する場合のファイル構成


  coreのファイル+
  hw_dep/microblazeのファイル+
  config_sample/microblaze/allのファイル

ライブラリのdefine設定

usbh_config.hのdefine設定によってCライブラリの構成が変わります。define定義に従って決まったメモリ量をあらかじめ静的に確保します。(Cライブラリでは実行時にメモリの動的確保を行いません。)

環境に関する設定

define名	説明
USBH_DEV_INITIAL_ADDRESS	エニュメレーション時にデバイスに割り当てるアドレスの初期値。デバイスが見つかると、USBH_DEV_INITIAL_ADDRESSに指定した値から順番にデバイスにアドレスが割り当てられる。
USBH_START_CONN	USBコネクタの開始番号。通常は0に設定。
USBH_NUM_OF_CONNS	使用するUSBコネクタの数。通常は1に設定。
USBH_NUM_OF_DEVICES	ライブラリで管理するデバイスの最大数。
USBH_MAX_INTERFACE	1つのデバイスが持つインターフェースの最大数。
USBH_MAX_ENDP	1つのインターフェースが持つエンドポイントの最大数
USBH_MAX_HUB_POR	HUBを使用する場合、そのHUBの最大ポート数
USBH_LOOKUP_MAX_CNT	ホストが管理するデバイス検索ルックアップテーブルの設定。マウス、キーボード等の種類別の最大登録数を指定。

使用するデバイスクラスの有効/無効設定

define名	説明
USBH_USE_HUB	HUBを使用する場合にdefineを行う。
USBH_USE_HID	マウス、キーボード、ゲームパッドを使用する場合にdefineを行う。
USBH_USE_MSD	USBフラッシュメモリ、SDカードリーダー等のストレージを使用する場合にdefineを行う。

HUBに関する設定

define名	説明
USBH_HUB_REPORT_MAX_BUF	“Hub and Port Status Change Bitmap”を格納するバッファのバイトサイズ。
USBH_HUB_CALLBACK	HUBにデバイスが脱着された時にコールバック関数による処理が必要な場合にdefineを行う。

HIDに関する設定

define名	説明
USBH_USE_MOUSE	マウスを使用する場合にdefineを行う。
USBH_USE_KEYBOARD	キーボードを使用する場合にdefineを行う。
USBH_USE_GAMEPAD	ゲームパッドを使用する場合にdefineを行う。
USBH_HID_REPORT_MAX_BUF	デバイスから取得したHIDのデータを格納するワークバッファのサイズ

マウスに関する設定

define名	説明
USBH_USE_MOUSE_BOOT_PROTOCOL	Boot Protocolを使用してマウスのデータを識別。
USBH_USE_MOUSE_BTN_IDX	マウスのボタンデータのインデックス値。(USBH_USE_MOUSE_BOOT_PROTOCOLがdefineされていない場合のみ有効)
USBH_USE_MOUSE_X_IDX	マウスのX軸移動量データのインデックス値。(USBH_USE_MOUSE_BOOT_PROTOCOLがdefineされていない場合のみ有効)
USBH_USE_MOUSE_Y_IDX	マウスのY軸移動量データのインデックス値。(USBH_USE_MOUSE_BOOT_PROTOCOLがdefineされていない場合のみ有効)
USBH_USE_MOUSE_Z_IDX	マウスのZ軸移動量データのインデックス値。(USBH_USE_MOUSE_BOOT_PROTOCOLがdefineされていない場合のみ有効)

キーボードに関する設定

define名	説明
USBH_HID_LANG_JAPANESE	日本語キーボードを使用する場合にdefineを行う。
USBH_USE_KEYBOARD_BOOT_PROTOCOL	Boot Protocolを使用してキーボードのデータを識別。
USBH_USE_KEYBOARD_M_IDX	キーボードのモデファイアデータのインデックス値。(USBH_USE_KEYBOARD_BOOT_PROTOCOLがdefineされていない場合のみ有効)
USBH_USE_KEYBOARD_K_IDX	キーボードのキーデータのインデックス値。(USBH_USE_KEYBOARD_BOOT_PROTOCOLがdefineされていない場合のみ有効)

ゲームパッドに関する設定

define名	説明
USBH_USE_REPORT_DESCRIPTOR	ゲームパッドの情報をReportディスクリプタから判別する場合にdefineを行う。
USBH_HID_REPORT_DESC_MAX_BUF	Reportディスクリプタ解析用ワークバッファのバイトサイズ。
USBH_USE_GAMEPAD_BTN_IDX	ゲームパッドのボタンデータのインデックス値。(USBH_USE_REPORT_DESCRIPTORがdefineされていない場合のみ有効)
USBH_USE_GAMEPAD_X_IDX	ゲームパッドのX方向データのインデックス値。(USBH_USE_REPORT_DESCRIPTORがdefineされていない場合のみ有効)
USBH_USE_GAMEPAD_Y_IDX	ゲームパッドのY方向データのインデックス値。(USBH_USE_REPORT_DESCRIPTORがdefineされていない場合のみ有効)
USBH_HID_SUPPORT_PS3_GC	PS3 Game Controllerを利用する場合にdefineを行う。

その他

define名	説明
INFO_PRINT	エニュメレーション中の情報などをコンソールに表示する場合にdefineを行う。

サンプルプログラム

プログラム名	説明
simple_mouse.c	マウスのみを利用する場合のサンプルプログラム。マウスの値が変化すると、コールバック関数が呼ばれてマウスの状態値がコンソールに表示される。
simple_mouse_hub.c	HUBにマウスが取り付けられた時と取り外された時にコールバック関数が呼ばれる。
simple_keyboard.c	キーボードのみを利用する場合のサンプルプログラム。キーが押されると、コールバック関数が呼ばれてキーに対応した文字がコンソールに表示される。
simple_gamepad.c	ゲームパッドのみを利用する場合のサンプルプログラム。ゲームパッドのボタンが押されると、コールバック関数が呼ばれてボタンの状態値がコンソールに表示される。
simple_msd_bot.c	USBメモリ等のストレージのみを利用する場合のサンプルプログラム。(ファイルシステムとしてFatFsを利用）
simple_msd_bot_pff.c	USBメモリ等のストレージのみを利用する場合のサンプルプログラム。(ファイルシステムとしてPetit FatFsを利用)
all_ff.c	すべてのサポートデバイスを利用する場合のサンプルプログラム。

プラットフォーム（ハードウェア）依存部分の初期化関数について

1.ul_hw_init関数の追加

uh_init関数(初期化関数)の先頭に、プラットフォーム依存部の初期化用としてul_hw_init関数の呼び出しを追加しました。
サンプルではhw_dep/nios2/usbh_hw.cとhw_dep/microblae/usbh_hw.cで実装を行っています。

2.ul_hw_device_setup関数の追加

デバイスの設定を行うum_device_setup関数内にul_hw_device_setup関数の呼び出しを追加しました。
ul_hw_device_setup関数の呼び出しタイミングは、デバイスのディスクリプタ取得後、そのデバイスのコンフィギュレーションやアドレスの設定を行う前です。サンプルではhw_dep/nios2/usbh_hw.cとhw_dep/microblae/usbh_hw.cで実装を行っています。（サンプルでは関数が呼ばれた確認用として、文字列表示のみを行っています。）

更新履歴


2013/10/01  公開
2013/10/31  USBH_HID_SUPPORT_PS3_GCを追加
2014/09/18  hw_dep以下の構成を変更
            simple_mouse_hub.cサンプルを追加
            サンプルのprintfをマクロ(MPRINT)に変更
            USBH_USE_HUB_CALLBACKのdefineを追加
            ul_hw_init関数の追加
            ul_hw_device_setup関数の追加